@homebound/form-state 2.33.0 → 3.1.0

package/dist/config.d.ts

@@ -1,78 +0,0 @@
-import { Fragment, ObjectState } from "./fields/objectField";
-import { Rule } from "./rules";
-import { Builtin, OmitIf } 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 type ObjectConfig<T> = {
-    [P in keyof OmitIf<T, Function>]: T[P] extends Fragment<infer V> ? FragmentFieldConfig : T[P] extends Array<infer U> | null | undefined ? U extends Builtin ? ValueFieldConfig<T[P]> : ListFieldConfig<U> : ValueFieldConfig<T[P]> | ObjectFieldConfig<T[P]>;
-};
-/** Field configuration for an opaque value that we don't actually want to include. */
-export type FragmentFieldConfig = {
-    type: "fragment";
-};
-/** Field configuration for primitive values, i.e. strings/numbers/Dates/user-defined types. */
-export type ValueFieldConfig<V> = {
-    type: "value";
-    rules?: Rule<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;
-    /** If true, we ignore field in dirty checks. */
-    isLocalOnly?: 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;
-    /** Marks an array field to be order agnostic when determining changed/dirty states, defaults true. */
-    strictOrder?: false;
-};
-/** Field configuration for list values, i.e. `U` is `Book` in a form with `books: Book[]`. */
-export type ListFieldConfig<U> = {
-    type: "list";
-    /** Rules that can run on the full list of children. */
-    rules?: Rule<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`.
-     *
-     * When deep-exhaustive, we include all rows in `changedValue` and also
-     * all fields in the child entities, i.e. not just placeholder `{ id: "b:1" }`
-     * values for otherwise-unchanged children.
-     *
-     * Defaults to `exhaustive` b/c that is the safest and also Joist's
-     * default behavior.
-     */
-    update?: "exhaustive" | "incremental" | "deep-exhaustive";
-    /** Set to not consider the order of the list when evaluating changed/dirty states, defaults true. */
-    strictOrder?: false;
-};
-export type ObjectFieldConfig<U> = {
-    type: "object";
-    /** Marks an object as a reference, which means we'll only include it's `id` in `changedValue` output. */
-    reference?: boolean;
-    /** Config for the child's form state, i.e. each book. */
-    config: ObjectConfig<U>;
-};

package/dist/config.js

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

package/dist/configBuilders.d.ts

@@ -1,67 +0,0 @@
-import { FragmentFieldConfig, ListFieldConfig, ObjectConfig, ObjectFieldConfig, ValueFieldConfig } from "./config";
-import { Fragment, ObjectState } from "./fields/objectField";
-import { Rule } from "./rules";
-import { Builtin, OmitIf } from "./utils";
-/**
- * Provides a Zod-ish API for building form configs.
- */
-export declare const f: {
-    /** Creates the top-level config for a form, like an author or book. */
-    config<T>(fields: ObjectConfigBuilderFields<T>): ObjectConfig<T>;
-    /** Creates the config DSL for an object, like an author or book. */
-    object<T>(fields: ObjectConfigBuilderFields<T>): ObjectConfigBuilder<T>;
-    /** Creates the config DSL for an list of objects, like an author's list of books. */
-    list<U>(fields: ObjectConfigBuilderFields<U>): ListFieldConfigBuilder<U>;
-    /** Creates the config DSL for a primitive value, like a first name or phone number. */
-    value<V>(): ValueFieldConfigBuilder<V>;
-    /** A shortcut for creating a child object with a single `id` key. */
-    reference<V extends {
-        id?: unknown;
-    }>(fields?: ObjectConfigBuilderFields<V>): ObjectConfigBuilder<V>;
-    /** A shorthand for creating a computed value. */
-    computed<V>(): ValueFieldConfigBuilder<V>;
-};
-/**
- * Defines the fields that should be passed into `f.object({ ... })` for fhe form type `T`.
- *
- * This is basically a map of `key` in `T` to `f.value()`, `f.list()`, or `f.object()`
- * DSL objects that define the runtime structure/fields of the form.
- */
-export type ObjectConfigBuilderFields<T> = {
-    [P in keyof OmitIf<T, Function>]: T[P] extends Fragment<infer V> ? FragmentFieldConfigBuilder : T[P] extends Array<infer U> | null | undefined ? U extends Builtin ? ValueFieldConfigBuilder<T[P]> : ListFieldConfigBuilder<U> : ValueFieldConfigBuilder<T[P]> | ObjectConfigBuilder<T[P]>;
-};
-export interface FragmentFieldConfigBuilder {
-    build(): FragmentFieldConfig;
-}
-/** Provides a fluent DSL for building up an object's config. */
-export declare class ObjectConfigBuilder<T> {
-    private config;
-    constructor(fields: ObjectConfigBuilderFields<T>);
-    ref(): this;
-    build(): ObjectFieldConfig<T>;
-}
-/** Provides a fluent DSL for building up a value's config. */
-export declare class ValueFieldConfigBuilder<V> {
-    private config;
-    /** Marks the field as required. */
-    req(): this;
-    /** Marks the field as read only. */
-    readOnly(): this;
-    /** Marks the field as local only. */
-    localOnly(): this;
-    /** Appends `rules` to the field's validation rules. */
-    rules(rules: Rule<V | null | undefined>[]): this;
-    /** Marks the field as computed. */
-    computed(): this;
-    build(): ValueFieldConfig<V>;
-}
-/** Provides a fluent DSL for building up a list's config. */
-export declare class ListFieldConfigBuilder<U> {
-    private config;
-    constructor(fields: ObjectConfigBuilderFields<U>);
-    /** Appends `rule` to the field's validation rules. */
-    rule(rule: Rule<readonly ObjectState<U>[]>): this;
-    /** Appends `rules` to the field's validation rules. */
-    rules(rules: Rule<readonly ObjectState<U>[]>[]): this;
-    build(): ListFieldConfig<U>;
-}

package/dist/configBuilders.js

@@ -1,115 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ListFieldConfigBuilder = exports.ValueFieldConfigBuilder = exports.ObjectConfigBuilder = exports.f = void 0;
-const rules_1 = require("./rules");
-/**
- * Provides a Zod-ish API for building form configs.
- */
-exports.f = {
-    /** Creates the top-level config for a form, like an author or book. */
-    config(fields) {
-        return new ObjectConfigBuilder(fields).build().config;
-    },
-    /** Creates the config DSL for an object, like an author or book. */
-    object(fields) {
-        return new ObjectConfigBuilder(fields);
-    },
-    /** Creates the config DSL for an list of objects, like an author's list of books. */
-    list(fields) {
-        return new ListFieldConfigBuilder(fields);
-    },
-    /** Creates the config DSL for a primitive value, like a first name or phone number. */
-    value() {
-        return new ValueFieldConfigBuilder();
-    },
-    /** A shortcut for creating a child object with a single `id` key. */
-    reference(fields) {
-        return exports.f.object({ id: exports.f.value(), ...fields }).ref();
-    },
-    /** A shorthand for creating a computed value. */
-    computed() {
-        return this.value().computed();
-    },
-};
-/** Provides a fluent DSL for building up an object's config. */
-class ObjectConfigBuilder {
-    constructor(fields) {
-        this.config = { type: "object", config: {} };
-        for (const [key, value] of Object.entries(fields)) {
-            this.config.config[key] = value.build();
-        }
-    }
-    ref() {
-        this.config.reference = true;
-        return this;
-    }
-    build() {
-        return this.config;
-    }
-}
-exports.ObjectConfigBuilder = ObjectConfigBuilder;
-/** Provides a fluent DSL for building up a value's config. */
-class ValueFieldConfigBuilder {
-    constructor() {
-        this.config = { type: "value", rules: [] };
-    }
-    /** Marks the field as required. */
-    req() {
-        this.config.rules = [rules_1.required];
-        return this;
-    }
-    /** Marks the field as read only. */
-    readOnly() {
-        this.config.readOnly = true;
-        return this;
-    }
-    /** Marks the field as local only. */
-    localOnly() {
-        this.config.isLocalOnly = true;
-        return this;
-    }
-    /** Appends `rules` to the field's validation rules. */
-    rules(rules) {
-        var _a;
-        var _b;
-        ((_a = (_b = this.config).rules) !== null && _a !== void 0 ? _a : (_b.rules = [])).push(...rules);
-        return this;
-    }
-    /** Marks the field as computed. */
-    computed() {
-        this.config.computed = true;
-        return this;
-    }
-    build() {
-        return this.config;
-    }
-}
-exports.ValueFieldConfigBuilder = ValueFieldConfigBuilder;
-/** Provides a fluent DSL for building up a list's config. */
-class ListFieldConfigBuilder {
-    constructor(fields) {
-        const config = {};
-        for (const [key, value] of Object.entries(fields)) {
-            config[key] = value.build();
-        }
-        this.config = { type: "list", rules: [], config };
-    }
-    /** Appends `rule` to the field's validation rules. */
-    rule(rule) {
-        var _a;
-        var _b;
-        ((_a = (_b = this.config).rules) !== null && _a !== void 0 ? _a : (_b.rules = [])).push(rule);
-        return this;
-    }
-    /** Appends `rules` to the field's validation rules. */
-    rules(rules) {
-        var _a;
-        var _b;
-        ((_a = (_b = this.config).rules) !== null && _a !== void 0 ? _a : (_b.rules = [])).push(...rules);
-        return this;
-    }
-    build() {
-        return this.config;
-    }
-}
-exports.ListFieldConfigBuilder = ListFieldConfigBuilder;

package/dist/configBuilders.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/configBuilders.test.js

@@ -1,65 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const configBuilders_1 = require("./configBuilders");
-describe("config", () => {
-    it("supports observable objects with helper methods in the config DSL", () => {
-        const config = configBuilders_1.f.config({
-            firstName: configBuilders_1.f.value(),
-            lastName: configBuilders_1.f.value(),
-            fullName: configBuilders_1.f.computed(),
-        });
-        // Throw away assertion, test is making sure ^ line compiles
-        expect(config).toBeDefined();
-    });
-    it("supports nested objects", () => {
-        const config = configBuilders_1.f.config({
-            id: configBuilders_1.f.value(),
-            address: configBuilders_1.f.object({ id: configBuilders_1.f.value() }),
-        });
-        expect(config).toMatchInlineSnapshot(`
-      {
-        "address": {
-          "config": {
-            "id": {
-              "rules": [],
-              "type": "value",
-            },
-          },
-          "type": "object",
-        },
-        "id": {
-          "rules": [],
-          "type": "value",
-        },
-      }
-    `);
-    });
-    it("supports Reference alias", () => {
-        const config = configBuilders_1.f.config({
-            id: configBuilders_1.f.value(),
-            address: configBuilders_1.f.reference({ name: configBuilders_1.f.value() }),
-        });
-        expect(config).toMatchInlineSnapshot(`
-      {
-        "address": {
-          "config": {
-            "id": {
-              "rules": [],
-              "type": "value",
-            },
-            "name": {
-              "rules": [],
-              "type": "value",
-            },
-          },
-          "reference": true,
-          "type": "object",
-        },
-        "id": {
-          "rules": [],
-          "type": "value",
-        },
-      }
-    `);
-    });
-});

package/dist/fields/deepEquals.d.ts

@@ -1,7 +0,0 @@
-/**
- * Our own `deepEquals` because either `fast-deep-equals` or `dequal` or etc actually
- * handle cyclic data structures, despite ChatGTP's assertions/hallucinations.
- *
- * Ported from https://github.com/KoryNunn/cyclic-deep-equal which is ISC.
- */
-export declare function deepEquals(a: any, b: any, visited?: Set<any>): boolean;

package/dist/fields/deepEquals.js

@@ -1,53 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.deepEquals = deepEquals;
-const temporal_1 = require("../temporal");
-/**
- * Our own `deepEquals` because either `fast-deep-equals` or `dequal` or etc actually
- * handle cyclic data structures, despite ChatGTP's assertions/hallucinations.
- *
- * Ported from https://github.com/KoryNunn/cyclic-deep-equal which is ISC.
- */
-function deepEquals(a, b, visited = new Set()) {
-    const temporalEquals = (0, temporal_1.areSupportedTemporalValuesEqual)(a, b);
-    if (temporalEquals !== undefined)
-        return temporalEquals;
-    const aType = typeof a;
-    if (aType !== typeof b)
-        return false;
-    if (a == null || b == null || !(aType === "object" || aType === "function")) {
-        if (aType === "number" && isNaN(a) && isNaN(b))
-            return true;
-        return a === b;
-    }
-    if (hasToJSON(a) || hasToJSON(b)) {
-        const a1 = hasToJSON(a) ? a.toJSON() : a;
-        const b1 = hasToJSON(b) ? b.toJSON() : b;
-        return deepEquals(a1, b1, visited);
-    }
-    if (Array.isArray(a) !== Array.isArray(b))
-        return false;
-    const aKeys = Object.keys(a), bKeys = Object.keys(b);
-    if (aKeys.length !== bKeys.length)
-        return false;
-    let equal = true;
-    for (const key of aKeys) {
-        if (!(key in b)) {
-            equal = false;
-            break;
-        }
-        if (a[key] && a[key] instanceof Object) {
-            if (visited.has(a[key]))
-                break;
-            visited.add(a[key]);
-        }
-        if (!deepEquals(a[key], b[key], visited)) {
-            equal = false;
-            break;
-        }
-    }
-    return equal;
-}
-function hasToJSON(o) {
-    return !!(o && typeof o === "object" && "toJSON" in o);
-}

package/dist/fields/fragmentField.d.ts

@@ -1,4 +0,0 @@
-export interface FragmentField<V> {
-    value: V;
-}
-export declare function newFragmentField<T extends object, K extends keyof T & string>(parentInstance: T, key: K): FragmentField<T[K]>;

package/dist/fields/fragmentField.js

@@ -1,58 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.newFragmentField = newFragmentField;
-const mobx_1 = require("mobx");
-const utils_1 = require("../utils");
-function newFragmentField(parentInstance, key) {
-    // 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 = (0, mobx_1.observable)({ value: 1 });
-    // We steal the fragment from our parent, so that it doesn't
-    // accidentally end up on the wire
-    let value = parentInstance[key];
-    delete parentInstance[key];
-    const obj = {
-        key,
-        _isIdKey: false,
-        _isDeleteKey: false,
-        _isReadOnlyKey: false,
-        _isLocalOnly: false,
-        touched: false,
-        valid: true,
-        readOnly: true,
-        required: false,
-        loading: false,
-        dirty: false,
-        focused: false,
-        originalValue: undefined,
-        changedValue: undefined,
-        errors: [],
-        rules: [],
-        isNewEntity: false,
-        focus: () => { },
-        blur: () => { },
-        maybeAutoSave: () => { },
-        commitChanges: () => { },
-        revertChanges: () => { },
-        get value() {
-            // Watch for our parentInstance changing
-            if (key in parentInstance) {
-                value = parentInstance[key];
-                delete parentInstance[key];
-            }
-            _tick.value > 0 || (0, utils_1.fail)();
-            return value;
-        },
-        set value(v) {
-            value = v;
-            _tick.value++;
-        },
-        set(value) {
-            this.value = value;
-        },
-        adapt(value) {
-            throw new Error("FragmentField does not support adapt");
-        },
-    };
-    return (0, mobx_1.makeAutoObservable)(obj, { value: false });
-}

package/dist/fields/listField.d.ts

@@ -1,11 +0,0 @@
-import { ListFieldConfig, ObjectFieldConfig } 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<U> extends FieldState<U[]> {
-    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>(parentCopy: T, parentInstance: T, parentState: () => ObjectState<T>, key: K, rules: Rule<readonly ObjectState<U>[]>[], listConfig: ListFieldConfig<U>, config: ObjectFieldConfig<U>, strictOrder: boolean, maybeAutoSave: () => void, deepExhaustive: boolean): ListFieldState<U>;