mobx-formly 0.0.2 → 0.0.3

package/dist/create-form.d.ts

@@ -0,0 +1,11 @@
+import { Form } from './form.js';
+import type { FieldValues, FormOptions, FormSchema, SchemaOutput } from './types.js';
+export type InferredFormValues<S> = Extract<SchemaOutput<S>, FieldValues>;
+/**
+ * Creates a form with values inferred from its schema.
+ *
+ * [**Documentation**](https://js2me.github.io/mobx-formly/guide/getting-started.html)
+ */
+export declare const createForm: <S extends FormSchema<any>>(options: FormOptions<InferredFormValues<S>> & {
+    schema: S;
+}) => Form<InferredFormValues<S>>;

package/dist/create-form.js

@@ -0,0 +1,7 @@
+import { Form } from './form.js';
+/**
+ * Creates a form with values inferred from its schema.
+ *
+ * [**Documentation**](https://js2me.github.io/mobx-formly/guide/getting-started.html)
+ */
+export const createForm = (options) => new Form(options);

package/dist/form.d.ts

@@ -0,0 +1,213 @@
+import { type Ref } from 'yummies/mobx';
+import type { FieldError, FieldErrors, FieldPath, FieldPathValue, FieldStateTree, FieldValues, FormOptions, RegisterOptions, RegisterReturn, ResetOptions, SetValueConfig, SubmitHandlers } from './types.js';
+export declare class Form<T extends FieldValues = FieldValues> {
+    /**
+     * Current form values.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#values)
+     */
+    values: T;
+    /**
+     * Validation errors nested by field path.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#errors)
+     */
+    private readonly errorsByPath;
+    private readonly errorPathCounts;
+    private readonly errorChildren;
+    private readonly errorProxyCache;
+    private readonly fieldStatesByPath;
+    private readonly fieldStatePathCounts;
+    private readonly fieldStateChildren;
+    private readonly fieldStateProxyCache;
+    /** Validation errors nested by field path. */
+    get errors(): FieldErrors<T>;
+    /**
+     * Field paths whose values differ from their defaults.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#dirtyfields)
+     */
+    dirtyFields: Record<string, true | undefined>;
+    /**
+     * Field paths that have been touched.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#touchedfields)
+     */
+    touchedFields: Record<string, true | undefined>;
+    /**
+     * Field paths that are currently being validated.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#validatingfields)
+     */
+    validatingFields: Record<string, true | undefined>;
+    /**
+     * Observable state for each registered field.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#fieldstate)
+     */
+    /** Observable state for each registered field, nested by field path. */
+    get fieldState(): FieldStateTree<T>;
+    /**
+     * Whether a submission is currently running.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#issubmitting)
+     */
+    isSubmitting: boolean;
+    /**
+     * Whether the form has been submitted at least once.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#issubmitted)
+     */
+    isSubmitted: boolean;
+    /**
+     * Whether the latest submission succeeded.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#issubmitsuccessful)
+     */
+    isSubmitSuccessful: boolean;
+    /**
+     * Number of submission attempts.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#submitcount)
+     */
+    submitCount: number;
+    /**
+     * Refs registered for fields.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#refs)
+     */
+    readonly refs: Map<string, Ref<HTMLElement | null, import("yummies/types").AnyObject>>;
+    private readonly defaultValues;
+    private readonly options;
+    private readonly fieldOptions;
+    private valueObservers?;
+    private observerTimer?;
+    private readonly changedPaths;
+    private isMutating;
+    private observerTreeChanged;
+    private activeSubmissions;
+    private resetVersion;
+    private validationVersion;
+    private readonly fieldValidationVersions;
+    /** Creates a form with optional initial values, schema, and validation settings.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#constructor-options)
+     */
+    constructor(options?: FormOptions<T>);
+    /**
+     * Whether registered event handlers ignore changes and blur events.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#disabled)
+     */
+    get disabled(): boolean;
+    /**
+     * Whether any field is dirty.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#isdirty)
+     */
+    get isDirty(): boolean;
+    /**
+     * Whether the form has no errors.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#isvalid)
+     */
+    get isValid(): boolean;
+    /**
+     * Registers a field and returns its ref and event handlers.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#registername-options)
+     */
+    register(name: FieldPath<T>, options?: RegisterOptions<T>): RegisterReturn;
+    /**
+     * Removes a field, its value, and its associated state.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#unregistername)
+     */
+    unregister(name: FieldPath<T>): void;
+    /**
+     * Updates a field value and optionally changes its state or validates it.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#setvaluename-value-config)
+     */
+    setValue<P extends FieldPath<T>>(name: P, value: FieldPathValue<T, P>, config?: SetValueConfig): void;
+    /**
+     * Groups direct value changes and processes their changed paths together.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#mutatemutator-config)
+     */
+    mutate(mutator: () => void, config?: SetValueConfig): void;
+    private applyValueChange;
+    private ensureValueObservers;
+    private scheduleObserverCleanup;
+    private disposeValueObservers;
+    private observeValueTree;
+    /**
+     * Sets an error for a field.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#seterrorname-error)
+     */
+    setError(name: FieldPath<T>, error: FieldError): void;
+    /**
+     * Clears one, several, or all field errors.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#clearerrorsname)
+     */
+    clearErrors(name?: FieldPath<T> | FieldPath<T>[]): void;
+    /**
+     * Validates one field, several fields, or the complete form.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#triggername)
+     */
+    trigger(name?: FieldPath<T> | FieldPath<T>[]): Promise<boolean>;
+    /**
+     * Creates an asynchronous submit handler with validation and result callbacks.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#handlesubmithandlers)
+     */
+    handleSubmit({ onValid, onInvalid }: SubmitHandlers<T>): () => Promise<void>;
+    /**
+     * Resets values and selected form state.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#resetvalues-options)
+     */
+    reset(values?: Partial<T>, options?: ResetOptions): void;
+    /**
+     * Resets one field to its current default value and clears its state.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#resetfieldname)
+     */
+    resetField(name: FieldPath<T>): void;
+    /**
+     * Focuses a registered field when its ref points to a focusable element.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#setfocusname)
+     */
+    setFocus(name: FieldPath<T>): void;
+    /**
+     * Returns a plain copy of the current values.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#snapshot)
+     */
+    get snapshot(): T;
+    private markTouched;
+    private updateDirty;
+    private shouldValidateOnChange;
+    private isValidationCurrent;
+    private transformValue;
+    private validateSchema;
+    private normalizeSchemaErrors;
+    private validateRules;
+    private ensureFieldState;
+    private applyFieldState;
+    private applyError;
+    private getError;
+    private hasError;
+    private errorPaths;
+    private deleteFieldState;
+    private fieldStates;
+    private setPathStore;
+    private deletePathStore;
+    private clearPathStore;
+    private addPathToIndex;
+    private createPathProxy;
+}

package/dist/form.js

@@ -0,0 +1,681 @@
+import { action, computed, makeObservable, observable, observe, runInAction } from 'mobx';
+import { createRef } from 'yummies/mobx';
+import { clone, deleteAtPath, extractValue, getAtPath, isEqual, setAtPath } from './utils.js';
+export class Form {
+    /**
+     * Current form values.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#values)
+     */
+    values;
+    /**
+     * Validation errors nested by field path.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#errors)
+     */
+    errorsByPath = observable.map();
+    errorPathCounts = observable.map();
+    errorChildren = new Map();
+    errorProxyCache = new Map();
+    fieldStatesByPath = observable.map();
+    fieldStatePathCounts = observable.map();
+    fieldStateChildren = new Map();
+    fieldStateProxyCache = new Map();
+    /** Validation errors nested by field path. */
+    get errors() {
+        return this.createPathProxy('', this.errorsByPath, this.errorPathCounts, this.errorChildren, this.errorProxyCache);
+    }
+    /**
+     * Field paths whose values differ from their defaults.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#dirtyfields)
+     */
+    dirtyFields = {};
+    /**
+     * Field paths that have been touched.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#touchedfields)
+     */
+    touchedFields = {};
+    /**
+     * Field paths that are currently being validated.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#validatingfields)
+     */
+    validatingFields = {};
+    /**
+     * Observable state for each registered field.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#fieldstate)
+     */
+    /** Observable state for each registered field, nested by field path. */
+    get fieldState() {
+        return this.createPathProxy('', this.fieldStatesByPath, this.fieldStatePathCounts, this.fieldStateChildren, this.fieldStateProxyCache);
+    }
+    /**
+     * Whether a submission is currently running.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#issubmitting)
+     */
+    isSubmitting = false;
+    /**
+     * Whether the form has been submitted at least once.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#issubmitted)
+     */
+    isSubmitted = false;
+    /**
+     * Whether the latest submission succeeded.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#issubmitsuccessful)
+     */
+    isSubmitSuccessful = false;
+    /**
+     * Number of submission attempts.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#submitcount)
+     */
+    submitCount = 0;
+    /**
+     * Refs registered for fields.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#refs)
+     */
+    refs = new Map();
+    defaultValues;
+    options;
+    fieldOptions = new Map();
+    valueObservers;
+    observerTimer;
+    changedPaths = new Set();
+    isMutating = false;
+    observerTreeChanged = false;
+    activeSubmissions = 0;
+    resetVersion = 0;
+    validationVersion = 0;
+    fieldValidationVersions = new Map();
+    constructor(options = {}) {
+        this.options = {
+            ...options,
+            mode: options.mode ?? 'onSubmit',
+            reValidateMode: options.reValidateMode ?? 'onChange',
+            disabled: options.disabled ?? false,
+        };
+        this.defaultValues = clone((options.defaultValues ?? {}));
+        this.values = clone((options.values ?? options.defaultValues ?? {}));
+        makeObservable(this, {
+            values: observable.deep,
+            dirtyFields: observable.shallow,
+            touchedFields: observable.shallow,
+            validatingFields: observable.shallow,
+            isSubmitting: observable,
+            isSubmitted: observable,
+            isSubmitSuccessful: observable,
+            submitCount: observable,
+            disabled: computed,
+            isDirty: computed,
+            isValid: computed,
+            snapshot: computed,
+            register: action,
+            unregister: action,
+            setValue: action,
+            mutate: action,
+            setError: action,
+            clearErrors: action,
+            trigger: action,
+            handleSubmit: action,
+            reset: action,
+            resetField: action,
+            setFocus: action,
+        });
+    }
+    /**
+     * Whether registered event handlers ignore changes and blur events.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#disabled)
+     */
+    get disabled() { return this.options.disabled; }
+    /**
+     * Whether any field is dirty.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#isdirty)
+     */
+    get isDirty() { return Object.keys(this.dirtyFields).length > 0; }
+    /**
+     * Whether the form has no errors.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#isvalid)
+     */
+    get isValid() { return this.errorsByPath.size === 0; }
+    /**
+     * Registers a field and returns its ref and event handlers.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#registername-options)
+     */
+    register(name, options = {}) {
+        const path = name;
+        this.fieldOptions.set(path, options);
+        let ref = this.refs.get(path);
+        if (!ref) {
+            ref = createRef();
+            this.refs.set(path, ref);
+        }
+        this.ensureFieldState(path);
+        return {
+            name: path,
+            ref,
+            onChange: async (eventOrValue) => {
+                if (this.disabled)
+                    return;
+                const value = this.transformValue(extractValue(eventOrValue), options);
+                const shouldValidate = this.shouldValidateOnChange(path);
+                this.setValue(path, value, { shouldDirty: true, shouldValidate: false });
+                if (shouldValidate)
+                    await this.trigger(path);
+            },
+            onBlur: async () => {
+                if (this.disabled)
+                    return;
+                this.markTouched(path);
+                if (this.options.mode === 'onBlur' || this.options.mode === 'all' || (this.hasError(path) && this.options.reValidateMode === 'onBlur'))
+                    await this.trigger(path);
+            },
+        };
+    }
+    /**
+     * Removes a field, its value, and its associated state.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#unregistername)
+     */
+    unregister(name) {
+        const path = name;
+        this.fieldValidationVersions.set(path, (this.fieldValidationVersions.get(path) ?? 0) + 1);
+        deleteAtPath(this.values, path);
+        this.applyError(path, undefined);
+        delete this.dirtyFields[path];
+        delete this.touchedFields[path];
+        delete this.validatingFields[path];
+        this.deleteFieldState(path);
+        this.fieldOptions.delete(path);
+        this.refs.delete(path);
+    }
+    /**
+     * Updates a field value and optionally changes its state or validates it.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#setvaluename-value-config)
+     */
+    setValue(name, value, config = {}) {
+        const path = name;
+        setAtPath(this.values, path, value);
+        this.applyValueChange(path, config);
+    }
+    /**
+     * Groups direct value changes and processes their changed paths together.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#mutatemutator-config)
+     */
+    mutate(mutator, config = {}) {
+        this.ensureValueObservers();
+        this.changedPaths.clear();
+        this.isMutating = true;
+        try {
+            mutator();
+        }
+        finally {
+            this.isMutating = false;
+        }
+        this.scheduleObserverCleanup();
+        const paths = [...this.changedPaths];
+        for (const path of paths)
+            this.applyValueChange(path, { ...config, shouldValidate: false });
+        if (paths.length && (config.shouldValidate ?? true)) {
+            void this.trigger(paths);
+        }
+        if (this.observerTreeChanged) {
+            this.disposeValueObservers();
+            this.observerTreeChanged = false;
+            this.ensureValueObservers();
+        }
+    }
+    applyValueChange(path, config) {
+        if (config.shouldDirty ?? true)
+            this.updateDirty(path);
+        if (config.shouldTouch)
+            this.markTouched(path);
+        if (config.shouldValidate)
+            void this.trigger(path);
+    }
+    ensureValueObservers() {
+        if (!this.valueObservers || this.observerTreeChanged) {
+            this.disposeValueObservers();
+            this.valueObservers = [];
+            this.observeValueTree(this.values, '', this.valueObservers);
+            this.observerTreeChanged = false;
+        }
+        this.scheduleObserverCleanup();
+    }
+    scheduleObserverCleanup() {
+        if (this.observerTimer)
+            clearTimeout(this.observerTimer);
+        this.observerTimer = setTimeout(() => this.disposeValueObservers(), 10 * 60 * 1000);
+        const timer = this.observerTimer;
+        timer.unref?.();
+    }
+    disposeValueObservers() {
+        for (const dispose of this.valueObservers ?? [])
+            dispose();
+        this.valueObservers = undefined;
+        this.observerTimer = undefined;
+    }
+    observeValueTree(value, basePath, disposers) {
+        if (!value || typeof value !== 'object')
+            return;
+        if (Array.isArray(value)) {
+            disposers.push(observe(value, (change) => {
+                if (change.type === 'splice')
+                    this.observerTreeChanged = true;
+                if (this.isMutating && basePath)
+                    this.changedPaths.add(basePath);
+            }));
+        }
+        else {
+            disposers.push(observe(value, (change) => {
+                if (change.type === 'update' && (typeof change.newValue === 'object' || typeof change.oldValue === 'object')) {
+                    this.observerTreeChanged = true;
+                }
+                if (!this.isMutating)
+                    return;
+                const path = basePath ? `${basePath}.${String(change.name)}` : String(change.name);
+                if (path)
+                    this.changedPaths.add(path);
+            }));
+        }
+        for (const [key, child] of Object.entries(value)) {
+            this.observeValueTree(child, basePath ? `${basePath}.${key}` : key, disposers);
+        }
+    }
+    /**
+     * Sets an error for a field.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#seterrorname-error)
+     */
+    setError(name, error) {
+        this.applyError(name, error);
+    }
+    /**
+     * Clears one, several, or all field errors.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#clearerrorsname)
+     */
+    clearErrors(name) {
+        if (!name) {
+            this.clearPathStore(this.errorsByPath, this.errorPathCounts, this.errorChildren);
+            for (const [, state] of this.fieldStates())
+                this.applyFieldState(state, undefined);
+            return;
+        }
+        for (const path of Array.isArray(name) ? name : [name])
+            this.applyError(path, undefined);
+    }
+    /**
+     * Validates one field, several fields, or the complete form.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#triggername)
+     */
+    async trigger(name) {
+        const paths = name ? (Array.isArray(name) ? name : [name]).map(String) : undefined;
+        const run = ++this.validationVersion;
+        const fieldVersions = new Map();
+        for (const path of paths ?? this.fieldOptions.keys()) {
+            if (this.fieldOptions.has(path))
+                fieldVersions.set(path, this.fieldValidationVersions.get(path) ?? 0);
+        }
+        for (const path of paths ?? this.fieldOptions.keys()) {
+            this.validatingFields[path] = true;
+            this.ensureFieldState(path).isValidating = true;
+        }
+        try {
+            const schemaErrors = await this.validateSchema();
+            const validationPaths = paths ?? [...new Set([...this.fieldOptions.keys(), ...this.errorsByPath.keys(), ...this.errorPaths(schemaErrors)])];
+            runInAction(() => {
+                for (const path of validationPaths) {
+                    const schemaError = this.getError(schemaErrors, path);
+                    if (schemaError && this.isValidationCurrent(path, run, fieldVersions)) {
+                        this.applyError(path, schemaError);
+                    }
+                }
+            });
+            for (const path of validationPaths) {
+                const ruleError = await this.validateRules(path);
+                runInAction(() => {
+                    if (this.isValidationCurrent(path, run, fieldVersions)) {
+                        if (ruleError)
+                            this.applyError(path, ruleError);
+                        else if (this.getError(schemaErrors, path))
+                            this.applyError(path, this.getError(schemaErrors, path));
+                        else
+                            this.applyError(path, undefined);
+                    }
+                });
+            }
+            return (paths ?? [...this.errorsByPath.keys()]).every((path) => !this.hasError(path));
+        }
+        finally {
+            runInAction(() => {
+                if (this.validationVersion === run) {
+                    for (const path of paths ?? this.fieldOptions.keys()) {
+                        if (!this.isValidationCurrent(path, run, fieldVersions))
+                            continue;
+                        delete this.validatingFields[path];
+                        this.ensureFieldState(path).isValidating = false;
+                    }
+                }
+            });
+        }
+    }
+    /**
+     * Creates an asynchronous submit handler with validation and result callbacks.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#handlesubmithandlers)
+     */
+    handleSubmit({ onValid, onInvalid }) {
+        return async () => {
+            this.activeSubmissions += 1;
+            this.isSubmitting = true;
+            this.isSubmitted = true;
+            this.submitCount += 1;
+            const submissionResetVersion = this.resetVersion;
+            try {
+                const valid = await this.trigger();
+                if (valid) {
+                    await onValid(this.snapshot, this);
+                    runInAction(() => {
+                        if (this.resetVersion === submissionResetVersion)
+                            this.isSubmitSuccessful = true;
+                    });
+                }
+                else {
+                    await onInvalid?.(this.errors, this);
+                    runInAction(() => {
+                        if (this.resetVersion === submissionResetVersion)
+                            this.isSubmitSuccessful = false;
+                    });
+                }
+            }
+            finally {
+                runInAction(() => {
+                    this.activeSubmissions -= 1;
+                    this.isSubmitting = this.activeSubmissions > 0;
+                });
+            }
+        };
+    }
+    /**
+     * Resets values and selected form state.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#resetvalues-options)
+     */
+    reset(values, options = {}) {
+        this.disposeValueObservers();
+        this.resetVersion += 1;
+        this.validationVersion += 1;
+        for (const path of Object.keys(this.validatingFields)) {
+            delete this.validatingFields[path];
+            const state = this.fieldStatesByPath.get(path);
+            if (state)
+                state.isValidating = false;
+        }
+        const next = clone((values ?? this.defaultValues));
+        this.values = next;
+        if (!options.keepDefaultValues && values)
+            Object.assign(this.defaultValues, clone(values));
+        if (!options.keepDirty)
+            this.dirtyFields = {};
+        if (!options.keepTouched)
+            this.touchedFields = {};
+        if (!options.keepErrors) {
+            this.clearPathStore(this.errorsByPath, this.errorPathCounts, this.errorChildren);
+            for (const [, state] of this.fieldStates())
+                this.applyFieldState(state, undefined);
+        }
+        if (!options.keepIsSubmitted) {
+            this.isSubmitted = false;
+            this.isSubmitSuccessful = false;
+        }
+        if (!options.keepSubmitCount)
+            this.submitCount = 0;
+        for (const [path, state] of this.fieldStates()) {
+            state.isDirty = !!this.dirtyFields[path];
+            state.isTouched = !!this.touchedFields[path];
+        }
+    }
+    /**
+     * Resets one field to its current default value and clears its state.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#resetfieldname)
+     */
+    resetField(name) {
+        const path = name;
+        this.fieldValidationVersions.set(path, (this.fieldValidationVersions.get(path) ?? 0) + 1);
+        setAtPath(this.values, path, clone(getAtPath(this.defaultValues, path)));
+        this.applyError(path, undefined);
+        delete this.dirtyFields[path];
+        delete this.touchedFields[path];
+        delete this.validatingFields[path];
+        const state = this.ensureFieldState(path);
+        this.applyFieldState(state, undefined);
+        state.isDirty = false;
+        state.isTouched = false;
+        state.isValidating = false;
+    }
+    /**
+     * Focuses a registered field when its ref points to a focusable element.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#setfocusname)
+     */
+    setFocus(name) { this.refs.get(name)?.current?.focus(); }
+    /**
+     * Returns a plain copy of the current values.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#snapshot)
+     */
+    get snapshot() { return clone(this.values); }
+    markTouched(path) {
+        this.touchedFields[path] = true;
+        this.ensureFieldState(path).isTouched = true;
+    }
+    updateDirty(path) {
+        if (isEqual(getAtPath(this.values, path), getAtPath(this.defaultValues, path)))
+            delete this.dirtyFields[path];
+        else
+            this.dirtyFields[path] = true;
+        this.ensureFieldState(path).isDirty = !!this.dirtyFields[path];
+    }
+    shouldValidateOnChange(path) { return this.options.mode === 'onChange' || this.options.mode === 'all' || (this.hasError(path) && this.options.reValidateMode === 'onChange'); }
+    isValidationCurrent(path, run, fieldVersions) {
+        if (this.validationVersion !== run)
+            return false;
+        const version = fieldVersions.get(path);
+        return version === undefined
+            || (this.fieldOptions.has(path) && (this.fieldValidationVersions.get(path) ?? 0) === version);
+    }
+    transformValue(value, options) {
+        if (options.setValueAs)
+            return options.setValueAs(value);
+        if (options.valueAsNumber)
+            return value === '' ? Number.NaN : Number(value);
+        if (options.valueAsDate)
+            return new Date(String(value));
+        return value;
+    }
+    async validateSchema() {
+        if (!this.options.schema)
+            return {};
+        const schema = this.options.schema;
+        if ('safeParseAsync' in schema) {
+            const result = await schema.safeParseAsync(this.snapshot);
+            if (result.success)
+                return {};
+            return this.normalizeSchemaErrors(result.error);
+        }
+        const result = await schema['~run']({ value: this.snapshot, typed: false }, {});
+        if (!result.issues?.length)
+            return {};
+        return this.normalizeSchemaErrors({ issues: result.issues });
+    }
+    normalizeSchemaErrors(error) {
+        return error.issues.reduce((errors, issue) => {
+            const path = (issue.path ?? []).map((part) => String(typeof part === 'object' ? part.key : part)).join('.') || 'root';
+            if (!this.getError(errors, path))
+                setAtPath(errors, path, { type: issue.code ?? issue.type ?? 'validation', message: issue.message });
+            return errors;
+        }, {});
+    }
+    async validateRules(path) {
+        const rules = this.fieldOptions.get(path);
+        if (!rules)
+            return undefined;
+        const value = getAtPath(this.values, path);
+        const fail = (type, rule) => typeof rule === 'string' ? { type, message: rule } : { type };
+        if (rules.required && (value === undefined || value === null || value === ''))
+            return fail('required', rules.required);
+        if (rules.minLength && String(value ?? '').length < rules.minLength.value)
+            return { type: 'minLength', message: rules.minLength.message };
+        if (rules.maxLength && String(value ?? '').length > rules.maxLength.value)
+            return { type: 'maxLength', message: rules.maxLength.message };
+        if (rules.min && Number(value) < rules.min.value)
+            return { type: 'min', message: rules.min.message };
+        if (rules.max && Number(value) > rules.max.value)
+            return { type: 'max', message: rules.max.message };
+        if (rules.pattern && !rules.pattern.value.test(String(value ?? '')))
+            return { type: 'pattern', message: rules.pattern.message };
+        if (rules.validate) {
+            let result;
+            try {
+                result = await rules.validate(value, this.snapshot);
+            }
+            catch {
+                return { type: 'validate', message: 'Validation failed' };
+            }
+            if (result !== true)
+                return { type: 'validate', message: typeof result === 'string' ? result : undefined };
+        }
+        return undefined;
+    }
+    ensureFieldState(path) {
+        const existing = this.fieldStatesByPath.get(path);
+        if (existing)
+            return existing;
+        const state = { invalid: false, isDirty: false, isTouched: false, isValidating: false };
+        this.setPathStore(this.fieldStatesByPath, this.fieldStatePathCounts, this.fieldStateChildren, path, state);
+        return state;
+    }
+    applyFieldState(state, error) {
+        state.error = error;
+        state.invalid = !!error;
+    }
+    applyError(path, error) {
+        if (error)
+            this.setPathStore(this.errorsByPath, this.errorPathCounts, this.errorChildren, path, error);
+        else
+            this.deletePathStore(this.errorsByPath, this.errorPathCounts, this.errorChildren, path);
+        this.applyFieldState(this.ensureFieldState(path), error);
+    }
+    getError(errors, path) {
+        const value = getAtPath(errors, path);
+        return value && typeof value === 'object' && 'type' in value ? value : undefined;
+    }
+    hasError(path) { return this.errorsByPath.has(path); }
+    errorPaths(errors, base = '') {
+        const paths = [];
+        for (const [key, value] of Object.entries(errors)) {
+            if (value === undefined)
+                continue;
+            const path = base ? `${base}.${key}` : key;
+            if (value && typeof value === 'object' && 'type' in value)
+                paths.push(path);
+            if (value && typeof value === 'object')
+                paths.push(...this.errorPaths(value, path));
+        }
+        return paths;
+    }
+    deleteFieldState(path) {
+        this.deletePathStore(this.fieldStatesByPath, this.fieldStatePathCounts, this.fieldStateChildren, path);
+    }
+    fieldStates() {
+        return [...this.fieldStatesByPath.entries()];
+    }
+    setPathStore(store, counts, children, path, value) {
+        if (!store.has(path))
+            this.addPathToIndex(counts, children, path);
+        store.set(path, value);
+    }
+    deletePathStore(store, counts, children, path) {
+        if (!store.delete(path))
+            return;
+        const parts = path.split('.');
+        for (let index = parts.length; index > 0; index -= 1) {
+            const current = parts.slice(0, index).join('.');
+            const count = (counts.get(current) ?? 1) - 1;
+            if (count > 0) {
+                counts.set(current, count);
+                continue;
+            }
+            counts.delete(current);
+            const parent = parts.slice(0, index - 1).join('.');
+            const siblings = children.get(parent);
+            siblings?.delete(parts[index - 1]);
+            if (siblings?.size === 0)
+                children.delete(parent);
+        }
+    }
+    clearPathStore(store, counts, children) {
+        store.clear();
+        counts.clear();
+        children.clear();
+    }
+    addPathToIndex(counts, children, path) {
+        const parts = path.split('.');
+        for (let index = 1; index <= parts.length; index += 1) {
+            const current = parts.slice(0, index).join('.');
+            counts.set(current, (counts.get(current) ?? 0) + 1);
+            const parent = parts.slice(0, index - 1).join('.');
+            let siblings = children.get(parent);
+            if (!siblings)
+                children.set(parent, siblings = new Set());
+            siblings.add(parts[index - 1]);
+        }
+    }
+    createPathProxy(path, store, counts, children, cache) {
+        const cached = cache.get(path);
+        if (cached)
+            return cached;
+        const proxy = new Proxy({}, {
+            get: (_, property) => {
+                if (typeof property !== 'string')
+                    return undefined;
+                const current = store.get(path);
+                if (current && property in current)
+                    return current[property];
+                const childPath = path ? `${path}.${property}` : property;
+                const value = store.get(childPath);
+                if (value && !children.has(childPath))
+                    return value;
+                return counts.has(childPath) ? this.createPathProxy(childPath, store, counts, children, cache) : undefined;
+            },
+            ownKeys: () => [...Object.keys(store.get(path) ?? {}), ...(children.get(path) ?? [])],
+            getOwnPropertyDescriptor: (_, property) => {
+                if (typeof property !== 'string')
+                    return undefined;
+                const value = store.get(path);
+                if (value && property in value)
+                    return { configurable: true, enumerable: true, value: value[property] };
+                return children.get(path)?.has(property) ? { configurable: true, enumerable: true } : undefined;
+            },
+            set: () => false,
+            deleteProperty: () => false,
+        });
+        cache.set(path, proxy);
+        return proxy;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Form } from './form.js';
+export { createForm } from './create-form.js';
+export type { InferredFormValues } from './create-form.js';
+export type { FieldError, FieldErrors, FieldPath, FieldPathValue, FieldState, FieldStateTree, FieldValues, FormOptions, FormSchema, SafeParseFormSchema, SchemaIssue, SchemaOutput, SchemaResult, ValibotFormSchema, ValibotRunResult, RegisterOptions, RegisterReturn, ResetOptions, SetValueConfig, SubmitHandlers, } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Form } from './form.js';
+export { createForm } from './create-form.js';

package/dist/types.d.ts

@@ -0,0 +1,140 @@
+import type { Ref } from 'yummies/mobx';
+export type FieldValues = Record<string, unknown>;
+export interface SchemaIssue {
+    code?: string;
+    type?: string;
+    path?: Array<PropertyKey | {
+        key: PropertyKey;
+    }>;
+    message: string;
+}
+export type SchemaResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: {
+        issues: SchemaIssue[];
+    };
+};
+/** Safe-parse-compatible schema contract. */
+export interface SafeParseFormSchema<T> {
+    safeParseAsync(value: unknown): Promise<SchemaResult<T>>;
+}
+/** Valibot-compatible schema contract. */
+export interface ValibotFormSchema<T> {
+    readonly '~types'?: {
+        readonly output: T;
+    };
+    '~run': (...args: any[]) => any;
+}
+export interface ValibotRunResult<T> {
+    success?: boolean;
+    value?: T;
+    issues?: SchemaIssue[];
+}
+/** Schema contract accepted by Form. Both Zod and Valibot schemas fit this interface. */
+export type FormSchema<T> = SafeParseFormSchema<T> | ValibotFormSchema<T>;
+export type SchemaOutput<S> = S extends SafeParseFormSchema<infer T> ? T : S extends {
+    readonly '~types'?: {
+        readonly output: infer T;
+    };
+} ? T : never;
+/** Dot-separated path into the form value tree, for example `user.email`. */
+export type FieldPath<T = FieldValues> = 'root' | {
+    [K in Extract<keyof T, string>]: T[K] extends readonly unknown[] ? T[K] extends readonly (infer I)[] ? I extends object ? K | `${K}.${number}` | `${K}.${number}.${FieldPath<I>}` : K | `${K}.${number}` : K : T[K] extends object ? K | `${K}.${FieldPath<T[K]>}` : K;
+}[Extract<keyof T, string>];
+export type FieldPathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? FieldPathValue<T[K], Rest> : T extends readonly (infer I)[] ? FieldPathValue<I, Rest> : never : P extends keyof T ? T[P] : T extends readonly (infer I)[] ? P extends `${number}` ? I : never : never;
+export interface FieldError {
+    type: string;
+    message?: string;
+}
+export type FieldErrors<T extends object = FieldValues> = {
+    [K in keyof T]?: T[K] extends readonly (infer I)[] ? FieldError & Array<I extends object ? FieldErrors<I> : FieldError | undefined> : T[K] extends object ? FieldError & FieldErrors<T[K]> : FieldError;
+} & {
+    root?: FieldError;
+};
+export interface FieldState {
+    invalid: boolean;
+    isDirty: boolean;
+    isTouched: boolean;
+    isValidating: boolean;
+    error?: FieldError;
+}
+export type FieldStateTree<T extends object = FieldValues> = {
+    [K in keyof T]?: T[K] extends readonly (infer I)[] ? FieldState & Array<I extends object ? FieldStateTree<I> : FieldState | undefined> : T[K] extends object ? FieldState & FieldStateTree<T[K]> : FieldState;
+} & {
+    root?: FieldState;
+};
+export interface FormState<T extends FieldValues = FieldValues> {
+    errors: FieldErrors<T>;
+    dirtyFields: Partial<Record<FieldPath<T>, true>>;
+    touchedFields: Partial<Record<FieldPath<T>, true>>;
+    validatingFields: Partial<Record<FieldPath<T>, true>>;
+    isDirty: boolean;
+    isValid: boolean;
+    isValidating: boolean;
+    isSubmitting: boolean;
+    isSubmitted: boolean;
+    isSubmitSuccessful: boolean;
+    submitCount: number;
+    disabled: boolean;
+}
+export interface RegisterOptions<T extends FieldValues = FieldValues> {
+    required?: string | boolean;
+    minLength?: {
+        value: number;
+        message?: string;
+    };
+    maxLength?: {
+        value: number;
+        message?: string;
+    };
+    min?: {
+        value: number;
+        message?: string;
+    };
+    max?: {
+        value: number;
+        message?: string;
+    };
+    pattern?: {
+        value: RegExp;
+        message?: string;
+    };
+    validate?: (value: unknown, values: T) => boolean | string | Promise<boolean | string>;
+    valueAsNumber?: boolean;
+    valueAsDate?: boolean;
+    setValueAs?: (value: unknown) => unknown;
+}
+export interface RegisterReturn {
+    name: string;
+    ref: Ref<HTMLElement | null>;
+    onChange: (eventOrValue: unknown) => Promise<void>;
+    onBlur: () => Promise<void>;
+}
+export interface SetValueConfig {
+    shouldValidate?: boolean;
+    shouldDirty?: boolean;
+    shouldTouch?: boolean;
+}
+export interface ResetOptions {
+    keepDefaultValues?: boolean;
+    keepDirty?: boolean;
+    keepTouched?: boolean;
+    keepErrors?: boolean;
+    keepIsSubmitted?: boolean;
+    keepSubmitCount?: boolean;
+}
+export interface FormOptions<T extends FieldValues> {
+    defaultValues?: Partial<T>;
+    values?: Partial<T>;
+    schema?: FormSchema<T>;
+    mode?: 'onSubmit' | 'onChange' | 'onBlur' | 'all';
+    reValidateMode?: 'onChange' | 'onBlur';
+    disabled?: boolean;
+}
+export interface SubmitHandlers<T extends FieldValues> {
+    onValid: (values: T, form: unknown) => void | Promise<void>;
+    onInvalid?: (errors: FieldErrors<T>, form: unknown) => void | Promise<void>;
+}

package/dist/types.js

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

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+export declare const clone: <T>(value: T) => T;
+export declare const getAtPath: (source: unknown, path: string) => unknown;
+export declare const setAtPath: (target: Record<string, unknown>, path: string, value: unknown) => void;
+export declare const deleteAtPath: (target: Record<string, unknown>, path: string) => void;
+export declare const isEqual: (a: unknown, b: unknown) => boolean;
+export declare const extractValue: (eventOrValue: unknown) => unknown;

package/dist/utils.js

@@ -0,0 +1,61 @@
+import { isUnsafeProperty } from 'yummies/data';
+export const clone = (value) => {
+    if (typeof structuredClone === 'function') {
+        try {
+            return structuredClone(value);
+        }
+        catch {
+            // MobX observable proxies cannot be structured-cloned directly.
+        }
+    }
+    return JSON.parse(JSON.stringify(value));
+};
+export const getAtPath = (source, path) => path.split('.').reduce((value, key) => {
+    if (isUnsafeProperty(key) || value === null || value === undefined)
+        return undefined;
+    return value[key];
+}, source);
+export const setAtPath = (target, path, value) => {
+    const keys = path.split('.');
+    let current = target;
+    for (const [index, key] of keys.slice(0, -1).entries()) {
+        if (isUnsafeProperty(key))
+            return;
+        const next = current[key];
+        const nextKey = keys[index + 1];
+        if (!next || typeof next !== 'object')
+            current[key] = /^\d+$/.test(nextKey) ? [] : {};
+        current = current[key];
+    }
+    const lastKey = keys.at(-1);
+    if (lastKey && !isUnsafeProperty(lastKey))
+        current[lastKey] = value;
+};
+export const deleteAtPath = (target, path) => {
+    const keys = path.split('.');
+    const lastKey = keys.pop();
+    if (!lastKey || isUnsafeProperty(lastKey))
+        return;
+    const parent = keys.reduce((value, key) => {
+        if (isUnsafeProperty(key) || !value || typeof value !== 'object')
+            return undefined;
+        return value[key];
+    }, target);
+    if (!parent || typeof parent !== 'object')
+        return;
+    delete parent[lastKey];
+};
+export const isEqual = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+export const extractValue = (eventOrValue) => {
+    if (!eventOrValue || typeof eventOrValue !== 'object' || !('target' in eventOrValue))
+        return eventOrValue;
+    const target = eventOrValue.target;
+    if (target.type === 'checkbox')
+        return target.checked;
+    if (target.type === 'radio')
+        return target.checked ? target.value : undefined;
+    if (target.multiple && typeof HTMLSelectElement !== 'undefined' && target instanceof HTMLSelectElement) {
+        return Array.from(target.selectedOptions, (option) => option.value);
+    }
+    return target.value;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobx-formly",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Framework-agnostic observable forms for MobX with granular field state and Zod or Valibot validation",
   "homepage": "https://js2me.github.io/mobx-formly/",
   "repository": {