mobx-formkit 1.0.0

package/src/Form.ts

@@ -0,0 +1,264 @@
+import {
+  action,
+  computed,
+  observable,
+  autorun,
+  runInAction,
+} from "mobx";
+import { makeObservable } from "./compat";
+import { debounce, each, merge } from "lodash";
+
+import Base from "./Base";
+import Validator from "./Validator";
+import State from "./State";
+import Field from "./Field";
+import ValidatorInterface from "./models/ValidatorInterface";
+import { FieldInterface, FieldConstructor } from "./models/FieldInterface";
+import {
+  FormInterface,
+  FieldsDefinitions,
+  FormConfig,
+  PathsOf,
+} from "./models/FormInterface";
+import { FieldPropsEnum } from "./models/FieldProps";
+import { OptionsEnum } from "./models/OptionsModel";
+
+export default class Form<F extends Record<string, any> = Record<string, any>> extends Base<F> implements FormInterface<F> {
+  name: string;
+  override path: any = null;
+  extra: Record<string, any> = {};
+  validator: ValidatorInterface;
+
+  debouncedValidation: any = null;
+
+  constructor(
+    setup: FieldsDefinitions = {},
+    {
+      name = "",
+      options = {},
+      plugins = {},
+      bindings = {},
+      hooks = {},
+      handlers = {},
+      extra = {},
+    }: FormConfig = {}
+  ) {
+    super();
+    makeObservable(this, {
+      extra: observable,
+      fields: observable,
+      flatMapValues: computed,
+      error: computed,
+      hasError: computed,
+      isValid: computed,
+      isPristine: computed,
+      isDirty: computed,
+      isDefault: computed,
+      isEmpty: computed,
+      focused: computed,
+      touched: computed,
+      disabled: computed,
+      // init: action,
+      invalidate: action,
+      clear: action,
+      reset: action,
+      resetValidation: action,
+    });
+
+    this.name = name;
+    this.extra = extra;
+    runInAction(() => (this.$hooks = hooks));
+    runInAction(() => (this.$handlers = handlers));
+
+    // load data from initializers methods
+    const initial = each(
+      {
+        setup,
+        options,
+        plugins,
+        bindings,
+      },
+      (val, key) =>
+        typeof (this as any)[key] === "function"
+          ? merge(val, (this as any)[key].apply(this, [this]))
+          : val
+    );
+
+    // setup hooks & handlers from initialization methods
+    runInAction(() =>
+      Object.assign(this.$hooks, (this as any).hooks?.apply(this, [this]))
+    );
+    runInAction(() =>
+      Object.assign(this.$handlers, (this as any).handlers?.apply(this, [this]))
+    );
+
+    this.state = new State({
+      form: this as any,
+      initial: initial.setup,
+      options: initial.options,
+      bindings: initial.bindings,
+    });
+
+    this.validator = new Validator({
+      form: this as any,
+      plugins: initial.plugins,
+    });
+
+    this.initFields(initial.setup);
+
+    this.debouncedValidation = debounce(
+      this.validate,
+      this.state.options.get(OptionsEnum.validationDebounceWait),
+      this.state.options.get(OptionsEnum.validationDebounceOptions)
+    );
+
+    // execute validation on form initialization
+    this.state.options.get(OptionsEnum.validateOnInit) &&
+      this.validator.validate({
+        showErrors: this.state.options.get(OptionsEnum.showErrorsOnInit),
+      });
+
+    this.execHook(FieldPropsEnum.onInit);
+
+    // handle Form onChange Hook
+    autorun(() => this.$changed && this.execHook(FieldPropsEnum.onChange));
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* COMPUTED */
+
+  get flatMapValues(): Record<string, any> {
+    const data: any = {};
+    this.each(($field: any) => (data[$field.path] = $field.validatedValue));
+    return data;
+  }
+
+  get error(): string | null {
+    return this.validator.error || this.firstError() || null;
+  }
+
+  get hasError(): boolean {
+    return !!this.validator.error || this.check(FieldPropsEnum.hasError, true);
+  }
+
+  get isValid(): boolean {
+    return !this.validator.error && this.check(FieldPropsEnum.isValid, true);
+  }
+
+  get isPristine(): boolean {
+    return this.check(FieldPropsEnum.isPristine, true);
+  }
+
+  get isDirty(): boolean {
+    return this.check(FieldPropsEnum.isDirty, true);
+  }
+
+  get isDefault(): boolean {
+    return this.check(FieldPropsEnum.isDefault, true);
+  }
+
+  get isEmpty(): boolean {
+    return this.check(FieldPropsEnum.isEmpty, true);
+  }
+
+  get focused(): boolean {
+    return this.check(FieldPropsEnum.focused, true);
+  }
+
+  get touched(): boolean {
+    return this.check(FieldPropsEnum.touched, true);
+  }
+
+  get disabled(): boolean {
+    return this.check(FieldPropsEnum.disabled, true);
+  }
+
+  makeField(data: FieldConstructor, FieldClass: typeof Field = Field) {
+    return new FieldClass(data);
+  }
+
+  /**
+   * Select a field by key with type inference.
+   * Provides transparent autocomplete for both top-level keys (`keyof F`)
+   * AND nested paths (`PathsOf<F>`) without any type annotations needed.
+   *
+   * @example
+   * // Top-level keys — autocomplete from keyof F:
+   * form.$('username'); // returns Field<string>
+   *
+   * @example
+   * // Nested paths — autocomplete from PathsOf<F>:
+   * form.$('club');                // "club"
+   * form.$('club.name');           // "club.name"  ← autocomplete after dot!
+   * form.$('members[].firstname'); // "members[].firstname"
+   */
+  override $(key: keyof F | PathsOf<F>): Field<F[keyof F]> {
+    return super.$(key as string) as Field<F[keyof F]>;
+  }
+
+  /**
+   * Select a field by path.
+   * For typed autocomplete, use `$()` instead, which is typed with `keyof F`.
+   */
+  override select(path: string | number, fields: any = null, isStrict: boolean = true): Field<any> {
+    return super.select(path, fields, isStrict) as Field<any>;
+  }
+
+  override values(): { [K in keyof F]?: F[K] } {
+    return super.values() as { [K in keyof F]?: F[K] };
+  }
+
+  /** DEPRECATED
+    Init Form Fields and Nested Fields
+
+  init($fields: any = null): void {
+    _.set(this, "fields", observable.map({}));
+
+    this.state.initial.props.values = $fields; // eslint-disable-line
+    this.state.current.props.values = $fields; // eslint-disable-line
+
+    this.initFields({
+      fields: $fields || this.state.struct(),
+    });
+  }
+  */
+
+  invalidate(message: string | null = null, deep: boolean = true): void {
+    this.debouncedValidation.cancel();
+    this.validator.error =
+      message ||
+      this.state.options.get(OptionsEnum.defaultGenericError) ||
+      null;
+    deep &&
+      this.each((field: FieldInterface) => field.debouncedValidation.cancel());
+  }
+
+  showErrors(show: boolean = true): void {
+    this.each((field: FieldInterface) => field.showErrors(show));
+  }
+
+  resetValidation(deep: boolean = true): void {
+    this.validator.error = null;
+    deep && this.each((field: FieldInterface) => field.resetValidation(deep));
+  }
+
+  /**
+    Clear Form Fields
+  */
+  clear(deep: boolean = true, execHook: boolean = true): void {
+    execHook && this.execHook(FieldPropsEnum.onClear);
+    this.$touched = false;
+    this.$changed = 0;
+    deep && this.each((field: FieldInterface) => field.clear(deep));
+  }
+
+  /**
+    Reset Form Fields
+  */
+  reset(deep: boolean = true, execHook: boolean = true): void {
+    execHook && this.execHook(FieldPropsEnum.onReset);
+    this.$touched = false;
+    this.$changed = 0;
+    deep && this.each((field: FieldInterface) => field.reset(deep));
+  }
+}

package/src/Options.ts

@@ -0,0 +1,91 @@
+import {
+  observable,
+  action,
+  toJS,
+  set,
+} from "mobx";
+import { makeObservable } from "./compat";
+
+import { get, has } from "lodash";
+
+import { uniqueId } from "./utils";
+
+import {OptionsModel} from "./models/OptionsModel";
+import {OptionsInterface} from "./models/OptionsInterface";
+
+export default class Options implements OptionsInterface {
+  options: OptionsModel = {
+    uniqueId,
+    fallback: true,
+    fallbackValue: "",
+    defaultGenericError: null,
+    submitThrowsError: true,
+    showErrorsOnInit: false,
+    showErrorsOnSubmit: true,
+    showErrorsOnBlur: true,
+    showErrorsOnChange: true,
+    showErrorsOnClear: false,
+    showErrorsOnReset: true,
+    validateOnInit: true,
+    validateOnSubmit: true,
+    validateOnBlur: true,
+    validateOnChange: false,
+    validateOnChangeAfterInitialBlur: false,
+    validateOnChangeAfterSubmit: false,
+    validateOnClear: false,
+    validateOnReset: false,
+    validateDisabledFields: false,
+    validateDeletedFields: false,
+    validatePristineFields: true,
+    strictSet: false,
+    strictUpdate: false,
+    strictDelete: true,
+    strictSelect: true,
+    softDelete: false,
+    retrieveOnlyDirtyFieldsValues: false,
+    retrieveOnlyEnabledFieldsValues: false,
+    retrieveOnlyEnabledFieldsErrors: false,
+    retrieveNullifiedEmptyStrings: false,
+    autoTrimValue: false,
+    autoParseNumbers: false,
+    removeNullishValuesInArrays: false,
+    preserveDeletedFieldsValues: false,
+    validationDebounceWait: 250,
+    validationDebounceOptions: {
+      leading: false,
+      trailing: true,
+    },
+    stopValidationOnError: false,
+    validationPluginsOrder: undefined,
+    resetValidationBeforeValidate: true,
+    validateTrimmedValue: false,
+    applyInputConverterOnInit: true,
+    applyInputConverterOnSet: true,
+    applyInputConverterOnUpdate: true,
+    bubbleUpErrorMessages: false,
+  };
+
+  constructor() {
+    makeObservable(this, {
+      options: observable,
+      set: action,
+    });
+  }
+
+  get(key: string = '', field: any = null): OptionsModel {
+    // handle field option
+    if (has(field, "path")) {
+      if (has(field.$options, key)) {
+        return field.$options[key];
+      }
+    }
+
+    // fallback on global form options
+    if (key) return get(this.options, key);
+    return toJS(this.options);
+  }
+
+  set(options: OptionsModel): void {
+    set(this.options, options);
+  }
+}

package/src/State.ts

@@ -0,0 +1,183 @@
+import { observe } from "mobx";
+import { get } from "lodash";
+
+import Options from "./Options";
+import Bindings from "./Bindings";
+
+import {
+  props,
+  hasUnifiedProps,
+  hasSeparatedProps,
+  checkObserve,
+  isArrayOfStrings,
+  $try,
+} from "./utils";
+
+import { RuntimeMode } from "./models/StateInterface";
+import { StateInterface } from "./models/StateInterface";
+import { OptionsInterface } from "./models/OptionsInterface";
+import { BindingsInterface } from "./models/BindingsInterface";
+import { FormInterface } from "./models/FormInterface";
+import { OptionsEnum } from "./models/OptionsModel";
+import { FieldInterface } from "./models/FieldInterface";
+
+export default class State implements StateInterface {
+  mode = RuntimeMode.mixed;
+
+  strict = false;
+
+  form!: FormInterface;
+
+  options: OptionsInterface;
+
+  bindings: BindingsInterface;
+
+  $extra: any;
+  $struct: string[] = [];
+
+  disposers = {
+    interceptor: {},
+    observer: {},
+  };
+
+  initial = {
+    props: {},
+    fields: {},
+  };
+
+  current = {
+    props: {},
+    fields: {},
+  };
+
+  constructor({ form, initial, options, bindings }: any) {
+    this.set("form", form);
+    this.initProps(initial);
+    this.options = new Options();
+    this.options.set(options);
+    this.bindings = new Bindings();
+    this.bindings.register(bindings);
+    this.observeOptions();
+  }
+
+  initProps(initial: any = {}) {
+    const pickKeys = [
+      ...props.editable,
+      ...props.separated,
+      ...props.validation,
+      ...props.functions,
+      ...props.handlers,
+    ];
+    const initialProps: any = Object.fromEntries(
+      Object.entries(initial).filter(([k]) => pickKeys.includes(k))
+    );
+
+    this.set("initial", "props", initialProps);
+
+    const $unified: boolean = hasUnifiedProps(initial);
+    const $separated: boolean = hasSeparatedProps(initial);
+
+    if (($separated || isArrayOfStrings(initial.fields)) && !$unified) {
+      const struct: any = $try(initial.struct, initial.fields);
+      this.struct(struct);
+      this.strict = true;
+      this.mode = RuntimeMode.separated;
+      return;
+    }
+
+    this.struct(initial.struct);
+    this.mode = RuntimeMode.unified;
+  }
+
+  /**
+    Get/Set Fields Structure
+  */
+  struct(data: any = null): any {
+    if (data) this.$struct = data;
+    return this.$struct;
+  }
+
+  /**
+    Get Props/Fields
+  */
+  get(type: string, subtype: string) {
+    return (this as any)[type][subtype];
+  }
+
+  /**
+    Set Props/Fields
+  */
+  set(type: string, subtype: any, state: any = null) {
+    if (type === "form") {
+      // subtype is the form here
+      this.form = subtype;
+    }
+
+    if (type === "initial") {
+      Object.assign((this.initial as any)[subtype], state);
+      Object.assign((this.current as any)[subtype], state);
+    }
+
+    if (type === "current") {
+      Object.assign((this.current as any)[subtype], state);
+    }
+  }
+
+  extra(data: any | null = null): any | null {
+    if (typeof data === 'string') return get(this.$extra, data);
+    if (data === null) return this.$extra;
+    this.$extra = data;
+    return null;
+  }
+
+  observeOptions(): void {
+    // Fix Issue #201
+    observe(
+      this.options.options,
+      checkObserve([
+        {
+          // start observing fields validateOnChange
+          type: "update",
+          key: OptionsEnum.validateOnChange,
+          to: true,
+          exec: () =>
+            this.form.each((field: FieldInterface) =>
+              field.observeValidationOnChange()
+            ),
+        },
+        {
+          // stop observing fields validateOnChange
+          type: "update",
+          key: OptionsEnum.validateOnChange,
+          to: false,
+          exec: () =>
+            this.form.each((field: FieldInterface) => {
+              if (typeof field.disposeValidationOnChange !== "function") return;
+              field.disposeValidationOnChange();
+            }),
+        },
+        {
+          // start observing fields validateOnBlur
+          type: "update",
+          key: OptionsEnum.validateOnBlur,
+          to: true,
+          exec: () =>
+            this.form.each((field: FieldInterface) =>
+              field.observeValidationOnBlur()
+            ),
+        },
+        {
+          // stop observing fields validateOnBlur
+          type: "update",
+          key: OptionsEnum.validateOnBlur,
+          to: false,
+          exec: () =>
+            this.form.each((field: FieldInterface) => {
+              if (typeof field.disposeValidationOnBlur !== "function") return;
+              field.disposeValidationOnBlur();
+            }),
+        },
+      ])
+    );
+  }
+}

package/src/Validator.ts

@@ -0,0 +1,177 @@
+import { action, observable } from "mobx";
+import { makeObservable } from "./compat";
+import { each } from "lodash";
+import { $try } from "./utils";
+import ValidatorInterface, {
+  DriversMap,
+  ValidateOptions,
+  ValidationPluginInterface,
+  ValidationPlugins,
+  ValidatorConstructor,
+} from "./models/ValidatorInterface";
+import { FormInterface } from "./models/FormInterface";
+import { FieldInterface } from "./models/FieldInterface";
+import { OptionsEnum } from "./models/OptionsModel";
+
+export default class Validator implements ValidatorInterface {
+  promises: Promise<any>[] = [];
+
+  form: FormInterface | null = null;
+
+  drivers: DriversMap = {};
+
+  plugins: ValidationPlugins = {
+    vjf: undefined,
+    dvr: undefined,
+    ajv: undefined,
+    yup: undefined,
+    zod: undefined,
+    joi: undefined,
+    valibot: undefined,
+    vinejs: undefined,
+  };
+
+  error: string | null = null;
+
+  constructor(obj: ValidatorConstructor) {
+    makeObservable(this, {
+      error: observable,
+      validate: action,
+      validateField: action,
+    });
+
+    this.form = obj.form;
+    Object.assign(this.plugins, obj.plugins);
+
+    this.initDrivers();
+  }
+
+  initDrivers(): void {
+    Object.entries(this.plugins).forEach(([key, plugin]) => {
+      this.drivers[key] = (plugin && (plugin as any).class) &&
+        new ((plugin as any).class)({
+          config: (plugin as any).config,
+          state: this.form!.state,
+          promises: this.promises,
+        });
+    });
+  }
+
+  validate(opt: ValidateOptions, obj: ValidateOptions): Promise<any> {
+    const path: string = $try((opt as any)?.path, opt);
+    const instance = $try((opt as any)?.field, this.form!.select(path, null, false), this.form!);
+    const related: boolean = $try((opt as any)?.related, (obj as any)?.related, true);
+    const showErrors: boolean = $try((opt as any)?.showErrors, (obj as any)?.showErrors, false);
+    instance.$validating = true;
+    instance.$validated += 1;
+
+    this.error = null;
+
+    return new Promise((resolve) => {
+      // validate instance (form or filed)
+      if (instance.path || typeof path === 'string') {
+        this.validateField({
+          field: instance,
+          showErrors,
+          related,
+          path,
+        });
+      }
+
+      // validate nested fields
+      instance.each((field: any) =>
+        this.validateField({
+          path: field.path,
+          field: field,
+          showErrors,
+          related,
+        })
+      );
+
+      // wait all promises
+      resolve(Promise.all(this.promises.splice(0)));
+    })
+      .then(
+        action(() => {
+          instance.$validating = false;
+          instance.$clearing = false;
+          instance.$resetting = false;
+        })
+      )
+      .catch(
+        action((err) => {
+          instance.$validating = false;
+          instance.$clearing = false;
+          instance.$resetting = false;
+          throw err;
+        })
+      )
+      .then(() => instance);
+  }
+
+  validateField({
+    showErrors = false,
+    related = false,
+    field = null,
+    path,
+  }: { showErrors?: boolean; related?: boolean; field?: any; path?: any }): void {
+    const instance = field || this.form!.select(path);
+    const { options } = this.form!.state;
+    // check if the field is a valid instance
+    if (!instance.path) throw new Error("Validation Error: Invalid Field Instance");
+    // do not validate soft deleted fields
+    if (instance.deleted && !options.get(OptionsEnum.validateDeletedFields, instance)) return;
+    // do not validate disabled fields
+    if (instance.disabled && !options.get(OptionsEnum.validateDisabledFields, instance)) return;
+    // do not validate pristine fields
+    if (instance.isPristine && !options.get(OptionsEnum.validatePristineFields, instance)) return;
+    // reset validation before validate
+    if (options.get(OptionsEnum.resetValidationBeforeValidate, instance)) instance.resetValidation();
+    // trim string value before validation
+    if (options.get(OptionsEnum.validateTrimmedValue, instance)) instance.trim();
+
+    // get stop on error
+    const stopOnError: boolean = options.get(
+      OptionsEnum.stopValidationOnError,
+      instance
+    );
+
+    // get validation plugin order
+    const validationPluginOrder = options.get(
+      OptionsEnum.validationPluginsOrder,
+      instance
+    );
+
+    const drivers: DriversMap = validationPluginOrder
+      ? validationPluginOrder.map((n: string) => this.drivers[n])
+      : this.drivers;
+
+    // validate with all enabled drivers
+    each(drivers, (driver: ValidationPluginInterface) => {
+      driver && driver.validate(instance);
+      if (stopOnError && instance.hasError) return;
+    });
+
+    // send error to the view
+    instance.showErrors(showErrors, false);
+
+    // related validation
+    if (related) this.validateRelatedFields(instance, showErrors);
+  }
+
+  /**
+    Validate 'related' fields if specified
+    and related validation allowed (recursive)
+  */
+  validateRelatedFields(field: FieldInterface, showErrors: boolean): void {
+    if (!field.related || !field.related.length) return;
+
+    field.related.map((path) =>
+      this.validateField({
+        related: false,
+        showErrors,
+        path,
+      })
+    );
+  }
+}