@homebound/form-state 2.32.0 → 3.0.0

package/dist/fields/listField.js

@@ -1,355 +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.newListFieldState = newListFieldState;
-const mobx_1 = require("mobx");
-const objectField_1 = require("./objectField");
-const rules_1 = require("../rules");
-const utils_1 = require("../utils");
-const object_hash_1 = __importDefault(require("object-hash"));
-function newListFieldState(
-// parentCopy is objectField's deepClone-d `originalCopy` that it/we use for `dirty` checking
-parentCopy, 
-// parentInstance is objectField's `instance`, that we're currently mutating
-parentInstance, parentState, key, rules, listConfig, config, strictOrder, maybeAutoSave, deepExhaustive) {
-    var _a;
-    // Keep a map of "item in the parentInstance list" -> "that item's ObjectState"
-    const rowMap = new Map();
-    const addedRows = new Set();
-    const _tick = (0, mobx_1.observable)({ value: 1 });
-    const _originalValueTick = (0, mobx_1.observable)({ value: 1 });
-    const _childTick = (0, mobx_1.observable)({ value: 1 });
-    // When child rows don't have ids (i.e. for new rows that aren't saved yet), we need an id-less
-    // "clone <-> current" map to tell if we're dirty or not, i.e. whether `parentInstance[key]` has
-    // drifted from `parentCopy[key]`
-    const copyMap = new Map();
-    ((_a = parentCopy[key]) !== null && _a !== void 0 ? _a : []).forEach((copy, i) => {
-        copyMap.set(copy, parentInstance[key][i]);
-    });
-    // Given a child POJO (or a copy/clone of a child POJO), return its ObjectState wrapper.
-    function getOrCreateChildState(child, opts) {
-        var _a;
-        let childState = rowMap.get(child);
-        // If we're being reverted to our originalValue, i.e. values is actually
-        // a list of copies, use the copyMap to recover the non-copy original value
-        if (!childState && copyMap.has(child)) {
-            childState = rowMap.get(copyMap.get(child));
-        }
-        // Look for an existing child (requires having an id key configured)
-        if (!childState) {
-            for (const [, otherState] of rowMap.entries()) {
-                if (otherState.isSameEntity(child)) {
-                    // If we're being called from `list.rows`, we should be careful to not trigger mutations
-                    if (!(opts === null || opts === void 0 ? void 0 : opts.skipSet))
-                        otherState.set(child, opts);
-                    rowMap.set(child, otherState);
-                    return otherState;
-                }
-            }
-        }
-        // If we didn't have an existing child, just make a new object state
-        if (!childState) {
-            childState = (0, objectField_1.newObjectState)(config, parentState, undefined, list, child, undefined, maybeAutoSave, (_a = listConfig.update === "deep-exhaustive") !== null && _a !== void 0 ? _a : deepExhaustive);
-            rowMap.set(child, childState);
-        }
-        return childState;
-    }
-    const list = {
-        key: key,
-        // Our fundamental state of wrapped Us
-        get value() {
-            var _a;
-            return _tick.value > 0 && _childTick.value > 0 ? ((_a = parentInstance[key]) !== null && _a !== void 0 ? _a : []) : (0, utils_1.fail)();
-        },
-        _kind: "list",
-        _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.hasChanged();
-        },
-        // Having a new entity is slightly different than being dirty, b/c merely having a placeholder-but-not-changed-yet
-        // `isNewEntity` child should not fire autosave (which would happen if we're dirty).
-        get hasNewEntity() {
-            return this.rows.some((r) => r.isNewEntity);
-        },
-        get focused() {
-            return this.rows.some((r) => r.focused);
-        },
-        get required() {
-            return this.rules.some((rule) => rule === rules_1.required);
-        },
-        get isNewEntity() {
-            return parentState().isNewEntity;
-        },
-        // private
-        /** Returns whether a row has been added/removed. */
-        hasChanged() {
-            const [current, original] = [this.value || [], this.originalValue];
-            if (current.length !== original.length)
-                return true;
-            if (strictOrder) {
-                // With strict order, every copy[i] === original[i] must be true
-                return original.some((e, idx) => current[idx] !== copyMap.get(e));
-            }
-            else {
-                // With loose order, we just want every copy to still have its original somewhere
-                return !original.every((e) => current.includes(copyMap.get(e)));
-            }
-        },
-        // 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)
-                (0, utils_1.fail)();
-            // Avoid using `this.value` to avoid registering `_childTick` as a dependency
-            const value = parentInstance[key];
-            return (value || []).map((child) => getOrCreateChildState(child, { skipSet: true }));
-        },
-        // TODO Should this be true when all rows are touched?
-        get touched() {
-            return this.rows.some((r) => r.touched) || this.hasChanged();
-        },
-        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: this.originalValue, 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)
-                (0, utils_1.fail)();
-            const opts = { value: this.rows, key: key, originalValue: this.originalValue, 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 = {}) {
-            var _a, _b, _c, _d, _e;
-            if (this.readOnly && !opts.resetting && !opts.refreshing) {
-                throw new Error(`${String(key)} is currently readOnly`);
-            }
-            // Given the values, see if we've got existing child states, and use their
-            // value if so. I.e. this covers revertChanges doing `set(originalValue)` and
-            // passing us cloned rows from the parentCopy, but `getOrCreateChildState` will
-            // use the `copyMap` to recover the non-cloned rows, to avoid promoting the clone
-            // into a real row.
-            if ((this.dirty || this.hasNewEntity) && opts.refreshing) {
-                // When refreshing a dirty list, we need to preserve WIP values
-                // Start with current list, then merge in incoming changes
-                //
-                // These will all be POJOs, where `currentItems` existing in our `parentInstance`, and
-                // `incomingItems` could really be any of:
-                // - an instance from `parentInstance[key]` that user code is passing back in
-                // - an instance from `parentCopy[key]` that a cache refresh is passing in
-                // - a new instance, either from a cache refresh or user code, that we haven't seen yet
-                const currentItems = this.value || [];
-                const incomingItems = values || [];
-                const mergedItems = [];
-                // Index by idKey or a hash of the object, so we don't have to n^2 merging
-                const idKey = this.rows.length > 0 && this.rows[0].idKey;
-                // Look at our child config, i.e. `bookConfig` and find the non-id / non-list keys
-                const contentKeys = Object.entries(config.config)
-                    .filter(([key, cfg]) => key !== idKey && cfg.type === "value")
-                    .map(([key]) => key);
-                const hashByContent = (item) => hashValue((0, utils_1.normalizeHashValue)(Object.fromEntries(Object.entries(item).filter(([key]) => contentKeys.includes(key)))));
-                const hashById = (item) => {
-                    const idValue = idKey ? item[idKey] : undefined;
-                    return idValue === undefined ? hashByContent(item) : idValue;
-                };
-                const currentById = (0, utils_1.groupBy)(currentItems, hashById);
-                const incomingById = (0, utils_1.groupBy)(incomingItems, hashById);
-                // If our local instance doesn't assign in id, when we get results back from the server, strip
-                // their id and then see if we're the same based on data. Note that this is a hueristic, and will
-                // fail if the client-side has made additional changes to the child after submitting it to the server,
-                // or if the server acks back more/different data than the client sent.
-                //
-                // Only do this if one of our client-side objects is missing an id
-                const incomingByContent = idKey && currentItems.some((item) => !item[idKey]) && (0, utils_1.groupBy)(incomingItems, hashByContent);
-                // Watch for deletions
-                const hasOpKey = Object.keys(listConfig.config).includes("op");
-                // First, process all current items
-                for (const currentItem of currentItems) {
-                    const childState = rowMap.get(currentItem); // We'll always have a child state for `currentItems`
-                    // Try to find a matching item in the incoming data
-                    const hash = hashById(currentItem);
-                    const match = ((_b = (_a = incomingById.get(hash)) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : 
-                    // Only if we don't have `book[id]` set, look for a match based on our content
-                    (!!idKey &&
-                        !currentItem[idKey] &&
-                        !!incomingByContent &&
-                        (
-                        // If we don't have an id, our `hash` variable will already be the `hashByContent`, so we can reuse it
-                        (_c = incomingByContent === null || incomingByContent === void 0 ? void 0 : incomingByContent.get(hash)) === null || _c === void 0 ? void 0 : _c[0])));
-                    if (match) {
-                        // Defer to set to handle not nuking WIP changes
-                        childState.set(match, opts);
-                        mergedItems.push(childState.value);
-                        // Once matched, we don't want this to be an addedRow anymore
-                        addedRows.delete(currentItem);
-                    }
-                    else if (!childState.dirty && !childState.isNewEntity && !addedRows.has(currentItem)) {
-                        // Local is not dirty/added, and it's not upstream, so let it get removed
-                    }
-                    else if (hasOpKey && currentItem.op === "delete") {
-                        // We were locally marked as deleted, and not finding a match is the server acking that we're gone
-                    }
-                    else if (currentItems.length === incomingItems.length &&
-                        !!idKey &&
-                        currentItem[idKey] === undefined) {
-                        // Assume our newly-assigned id is coming back
-                    }
-                    else {
-                        // If no incoming, but we're dirty (see above) and not deleted (see above), keep the WIP change
-                        mergedItems.push(currentItem);
-                    }
-                }
-                // Then, add any incoming items that don't exist in current
-                for (const incomingItem of incomingItems) {
-                    // Look for both `incoming.id` and the incoming-sans-id for new entities
-                    const match = ((_d = currentById.get(hashById(incomingItem))) === null || _d === void 0 ? void 0 : _d[0]) || ((_e = currentById.get(hashByContent(incomingItem))) === null || _e === void 0 ? void 0 : _e[0]);
-                    if (!match) {
-                        // New item from server, add it
-                        const childState = getOrCreateChildState(incomingItem, opts);
-                        mergedItems.push(childState.value);
-                    }
-                }
-                parentInstance[key] = mergedItems;
-                _tick.value++;
-                // Set original to not merged...
-                this.setOriginalValue(incomingItems);
-            }
-            else {
-                parentInstance[key] = (values !== null && values !== void 0 ? values : []).map((child) => getOrCreateChildState(child, opts).value);
-                _tick.value++;
-                // Reset originalCopy so that our dirty checks have the right # of rows.
-                if (opts.refreshing) {
-                    this.setOriginalValue();
-                }
-            }
-        },
-        add(value, spliceIndex) {
-            // This is called by the user, so value should be a non-proxy value we should keep
-            const childState = getOrCreateChildState(value);
-            rowMap.set(value, childState);
-            // Let `.set` know this is a new row
-            addedRows.add(value);
-            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();
-        },
-        revertChanges() {
-            this.set(this.originalValue, { resetting: true });
-            this.rows.forEach((r) => r.revertChanges());
-            this.touched = false;
-        },
-        commitChanges() {
-            // Tell each child ObjectState to have its fields commit into its parentCopy
-            this.rows.forEach((r) => r.commitChanges());
-            this.setOriginalValue();
-            this.touched = false;
-            _tick.value++;
-        },
-        get originalValue() {
-            // A dummy check to for reactivity around our non-proxy value
-            const value = _originalValueTick.value > -1 ? parentCopy[key] : parentCopy[key];
-            return value !== null && value !== void 0 ? value : [];
-        },
-        // This should only be called when value === originalValue
-        setOriginalValue(incomingItems) {
-            // Use the rows' originalValues to update the parentCopy
-            parentCopy[key] = incomingItems !== null && incomingItems !== void 0 ? incomingItems : this.rows.map((r) => r.originalValue);
-            parentCopy[key].forEach((copy, i) => {
-                copyMap.set(copy, parentInstance[key][i]);
-            });
-            _originalValueTick.value++;
-        },
-        ensureSet() {
-            if (!parentInstance[key]) {
-                parentInstance[key] = [];
-            }
-            _tick.value++;
-        },
-    };
-    const proxy = (0, mobx_1.makeAutoObservable)(list, {
-        // See other makeAutoObservable comment
-        value: (0, mobx_1.computed)({ equals: () => false }),
-    });
-    // Any time a row's value changes, percolate that to our `.value` (so the callers to our
-    // `.value` will rerun given the value they saw has deeply changed.)
-    (0, mobx_1.reaction)(() => proxy.rows.map((r) => r.value), () => _childTick.value++);
-    return proxy;
-}
-function hashValue(value) {
-    return (0, object_hash_1.default)(value);
-}

package/dist/fields/objectField.d.ts

@@ -1,63 +0,0 @@
-import { ObjectConfig, ObjectFieldConfig } from "../config";
-import { FragmentField } from "./fragmentField";
-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 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 type ObjectState<T> = FieldStates<T> & FieldState<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 type ObjectStateInternal<T = unknown> = ObjectState<T> & {
-    set(value: T, opts?: InternalSetOpts): void;
-    isSameEntity(other: T): boolean;
-    idKey: string | undefined;
-};
-declare const fragmentSym: unique symbol;
-export type Fragment<V> = V & {
-    [fragmentSym]: true;
-};
-export declare function fragment<V>(value: V): Fragment<V>;
-/** 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. */
-type FieldStates<T> = {
-    [K in keyof T]-?: T[K] extends Fragment<infer V> ? FragmentField<V> : T[K] extends Array<infer U> | null | undefined ? [U] extends [Builtin] ? FieldState<T[K]> : ListFieldState<U> : T[K] extends Builtin | null | undefined ? FieldState<T[K]> : ObjectState<T[K]>;
-};
-/**
- * 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>;
-/** A more internal version of `createObjectState`. */
-export declare function newObjectState<T, P = any>(config: ObjectFieldConfig<T>, parentState: (() => ObjectState<P>) | undefined, parentInstance: P | undefined, parentListState: FieldState<any> | undefined, instance: T, key: keyof T | undefined, maybeAutoSave: () => void, deepExhaustive: boolean): ObjectState<T>;
-export {};