mobx-formly 0.0.3 → 0.1.1

package/dist/create-form.d.ts

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

package/dist/create-form.js

@@ -1,7 +1,5 @@
-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);
+import { BaseForm } from './form.js';
+// Implementation signature is intentionally loose: callers only see the typed overloads above.
+export function createForm(...args) {
+    return new BaseForm(args[0] ?? {});
+}

package/dist/form.d.ts

@@ -1,25 +1,215 @@
 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> {
+import type { ErrorNamespacePath, FieldError, FieldErrors, FieldPath, FieldPathValue, FieldStateTree, FieldValues, FormOptions, RegisterOptions, RegisterReturn, ResetFieldOptions, ResetOptions, SetErrorConfig, SetValueConfig, SubmitHandlers, TriggerConfig } from './types.js';
+/**
+ * Public form contract returned by `createForm()` and implemented by `BaseForm`.
+ *
+ * Coordinates form values, field registration, validation, and submission
+ * without any rendering concerns.
+ *
+ * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html)
+ */
+export interface Form<T extends FieldValues = FieldValues> {
     /**
      * Current form values.
      *
      * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#values)
      */
     values: T;
+    /**
+     * Cached default values used by reset, resetField, and dirty comparison.
+     * Updated by reset unless `keepDefaultValues` is passed.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#defaultvalues)
+     */
+    defaultValues: 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;
+    readonly 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, nested by field path.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#fieldstate)
+     */
+    readonly 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>>;
+    /**
+     * Whether registered event handlers ignore changes and blur events.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#disabled)
+     */
+    readonly disabled: boolean;
+    /**
+     * Whether any field is dirty.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#isdirty)
+     */
+    readonly isDirty: boolean;
+    /**
+     * Whether any field has been touched.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#istouched)
+     */
+    readonly isTouched: boolean;
+    /**
+     * Whether any field validation is currently running.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#isvalidating)
+     */
+    readonly isValidating: boolean;
+    /**
+     * Whether the form has no errors. With a schema or resolver the first read
+     * schedules a full validation pass, so validity reflects the schema instead
+     * of defaulting to true until something validates.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#isvalid)
+     */
+    readonly isValid: boolean;
+    /**
+     * Returns a plain copy of the current values.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#snapshot)
+     */
+    readonly snapshot: T;
+    /**
+     * 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;
+    /**
+     * Returns the stable MobX-aware ref for a field path, creating it on demand.
+     * The ref can be used by a view adapter before the field is registered.
+     */
+    ref(name: FieldPath<T>): Ref<HTMLElement | null>;
+    /**
+     * 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, reconciles all dirty paths, and optionally
+     * validates the complete form.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#mutatemutator-config)
+     */
+    mutate(mutator: () => Promise<void>, config?: SetValueConfig): Promise<void>;
+    mutate(mutator: () => void, config?: SetValueConfig): void;
+    /**
+     * Sets an error for a field and can focus it.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#seterrorname-error)
+     */
+    setError(name: FieldPath<T> | ErrorNamespacePath, error: FieldError, config?: SetErrorConfig): void;
+    /**
+     * Clears one, several, or all field errors.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#clearerrorsname)
+     */
+    clearErrors(name?: FieldPath<T> | ErrorNamespacePath | Array<FieldPath<T> | ErrorNamespacePath>): 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>[], config?: TriggerConfig): Promise<boolean>;
+    /**
+     * Creates an asynchronous submit handler with validation and result callbacks.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#handlesubmithandlers)
+     */
+    handleSubmit(handlers: 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<P extends FieldPath<T>>(name: P, options?: ResetFieldOptions<T, P>): 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;
+}
+export declare class BaseForm<T extends FieldValues = FieldValues> implements Form<T> {
+    /**
+     * Current form values.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#values)
+     */
+    values: T;
+    /**
+     * Cached default values used by reset, resetField, and dirty comparison.
+     * Updated by reset unless `keepDefaultValues` is passed.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#defaultvalues)
+     */
+    defaultValues: T;
+    private readonly errorStore;
+    private readonly fieldStateStore;
     /** Validation errors nested by field path. */
     get errors(): FieldErrors<T>;
     /**
@@ -41,11 +231,10 @@ export declare class Form<T extends FieldValues = FieldValues> {
      */
     validatingFields: Record<string, true | undefined>;
     /**
-     * Observable state for each registered field.
+     * Observable state for each registered field, nested by field path.
      *
      * [**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.
@@ -77,18 +266,17 @@ export declare class Form<T extends FieldValues = FieldValues> {
      * [**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 readonly touchedValidationFields;
+    private readonly validator;
     private activeSubmissions;
     private resetVersion;
+    private readonly isValidOverride;
     private validationVersion;
     private readonly fieldValidationVersions;
+    /** Whether at least one validation pass has completed since construction or reset. */
+    private hasValidationRun;
     /** Creates a form with optional initial values, schema, and validation settings.
      *
      * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#constructor-options)
@@ -107,7 +295,17 @@ export declare class Form<T extends FieldValues = FieldValues> {
      */
     get isDirty(): boolean;
     /**
-     * Whether the form has no errors.
+     * Whether any field has been touched.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#istouched)
+     */
+    get isTouched(): boolean;
+    /** Whether any field validation is currently running. */
+    get isValidating(): boolean;
+    /**
+     * Whether the form has no errors. With a schema or resolver the first read
+     * schedules a full validation pass, so validity reflects the schema instead
+     * of defaulting to true until something validates.
      *
      * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#isvalid)
      */
@@ -118,6 +316,11 @@ export declare class Form<T extends FieldValues = FieldValues> {
      * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#registername-options)
      */
     register(name: FieldPath<T>, options?: RegisterOptions<T>): RegisterReturn;
+    /**
+     * Returns the stable MobX-aware ref for a field path, creating it on demand.
+     * The ref can be used by a view adapter before the field is registered.
+     */
+    ref(name: FieldPath<T>): Ref<HTMLElement | null>;
     /**
      * Removes a field, its value, and its associated state.
      *
@@ -131,34 +334,34 @@ export declare class Form<T extends FieldValues = FieldValues> {
      */
     setValue<P extends FieldPath<T>>(name: P, value: FieldPathValue<T, P>, config?: SetValueConfig): void;
     /**
-     * Groups direct value changes and processes their changed paths together.
+     * Groups direct value changes, reconciles all dirty paths, and optionally
+     * validates the complete form.
      *
      * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#mutatemutator-config)
      */
+    mutate(mutator: () => Promise<void>, config?: SetValueConfig): Promise<void>;
     mutate(mutator: () => void, config?: SetValueConfig): void;
+    private finishMutation;
     private applyValueChange;
-    private ensureValueObservers;
-    private scheduleObserverCleanup;
-    private disposeValueObservers;
-    private observeValueTree;
     /**
-     * Sets an error for a field.
+     * Sets an error for a field and can focus it.
      *
      * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#seterrorname-error)
      */
-    setError(name: FieldPath<T>, error: FieldError): void;
+    setError(name: FieldPath<T> | ErrorNamespacePath, error: FieldError, config?: SetErrorConfig): 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;
+    clearErrors(name?: FieldPath<T> | ErrorNamespacePath | Array<FieldPath<T> | ErrorNamespacePath>): 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>;
+    trigger(name?: FieldPath<T> | FieldPath<T>[], config?: TriggerConfig): Promise<boolean>;
+    private runValidation;
     /**
      * Creates an asynchronous submit handler with validation and result callbacks.
      *
@@ -176,7 +379,7 @@ export declare class Form<T extends FieldValues = FieldValues> {
      *
      * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#resetfieldname)
      */
-    resetField(name: FieldPath<T>): void;
+    resetField<P extends FieldPath<T>>(name: P, options?: ResetFieldOptions<T, P>): void;
     /**
      * Focuses a registered field when its ref points to a focusable element.
      *
@@ -189,25 +392,20 @@ export declare class Form<T extends FieldValues = FieldValues> {
      * [**Documentation**](https://js2me.github.io/mobx-formly/api/form.html#snapshot)
      */
     get snapshot(): T;
+    /** Reconciles dirty paths against the complete current value tree. */
+    private syncDirtyFields;
+    /** Clears an exact error path and every nested error below it. */
+    private clearErrorPath;
+    /** Focuses the first errored registered field, skipping form-level errors. */
+    private focusFirstError;
+    private dependentFields;
     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;
 }