mobx-formkit 1.0.0

package/src/compat.ts

@@ -0,0 +1,104 @@
+import * as mobx from "mobx";
+
+// `decorate` was removed in MobX 7 and `makeObservable` does not exist in
+// MobX 5. Resolve both lazily through the module namespace so a static
+// named import never fails at link time (MISSING_EXPORT) with MobX 7.
+const M = mobx as any;
+
+type Annotations = Record<string, any>;
+
+/**
+ * `makeObservable` with MobX 5 / 6 / 7 compatibility.
+ *
+ * MobX 6/7: delegates to the native `makeObservable`.
+ * MobX 5: `makeObservable` does not exist (introduced in 6.0). The fallback
+ * below re-implements the same semantics with the MobX 5 primitives:
+ *
+ * 1. every annotated member is materialized as an OWN property of the
+ *    instance first (getters/setters are copied down from the prototype
+ *    chain — e.g. `changed`/`submitted` live on `Base`, not on `Form`),
+ * 2. a single `decorate(instance, ...)` pass applies the corresponding
+ *    `observable` / `computed` / `action` decorators.
+ *
+ * Decorating the instance (instead of the prototype) is required: MobX 5's
+ * `decorate` is lazy (`mobxPendingDecorators`) and its initializer accessors
+ * recurse infinitely when decorated members live on the prototype, while a
+ * computed needs the getter to be an OWN property of the decorated target.
+ * `extendObservable` is avoided too — passing `ComputedValue` instances as
+ * initial values is no longer supported in 5.15+.
+ *
+ * All other APIs used across the source (`action`, `set`, `toJS`, `observe`,
+ * `intercept`, `reaction`, `autorun`, `runInAction`, `untracked`,
+ * `configure`/`enforceActions`, `extendObservable`) exist unchanged in
+ * MobX 5.x, 6.x and 7.x, so no other shims are required.
+ */
+export const makeObservable = (target: any, annotations: Annotations): any => {
+  if (typeof M.makeObservable === "function") {
+    return M.makeObservable(target, annotations);
+  }
+
+  return fallbackMakeObservable(target, annotations);
+};
+
+/* istanbul ignore next -- MobX 5 only: no makeObservable in 5.x and no decorate in 6/7, not runnable on the MobX 6/7 test matrix */
+function fallbackMakeObservable(target: any, annotations: Annotations): any {
+  const members = Object.entries(annotations).filter(([key]) =>
+    key in target
+  );
+  // call sites pass the mobx exports themselves (e.g. `computed`, `action`,
+  // `observable`) — compare by value, not by string
+  const isComputed = (annotation: any) =>
+    annotation === M.computed || annotation === "computed";
+  const isAction = (annotation: any) =>
+    annotation === M.action || annotation === "action";
+
+  const descriptorFromChain = (key: string) => {
+    let currentProto = Object.getPrototypeOf(target);
+    let descriptor: PropertyDescriptor | undefined;
+    while (currentProto && descriptor === undefined) {
+      descriptor = Object.getOwnPropertyDescriptor(currentProto, key);
+      currentProto = Object.getPrototypeOf(currentProto);
+    }
+    return descriptor;
+  };
+
+  members.forEach(([key, annotation]) => {
+    if (isComputed(annotation)) {
+      const own = Object.getOwnPropertyDescriptor(target, key);
+      if (!own || typeof own.get !== "function") {
+        const chain = descriptorFromChain(key);
+        const chainGet =
+          chain && typeof chain.get === "function" ? chain.get : null;
+        const chainSet =
+          chain && typeof chain.set === "function" ? chain.set : null;
+        Object.defineProperty(target, key, {
+          configurable: true,
+          enumerable: chain ? chain.enumerable : false,
+          get: chainGet ? () => chainGet.call(target) : () => undefined,
+          set: chainSet ? (value: any) => chainSet.call(target, value) : undefined,
+        });
+      }
+    } else if (isAction(annotation)) {
+      const value = target[key];
+      if (typeof value === "function" &&
+          !Object.prototype.hasOwnProperty.call(target, key)) {
+        Object.defineProperty(target, key, {
+          configurable: true,
+          writable: true,
+          enumerable: false,
+          value,
+        });
+      }
+    }
+  });
+
+  const decorators: Record<string, any> = {};
+  members.forEach(([key, annotation]) => {
+    if (isComputed(annotation)) decorators[key] = M.computed;
+    else if (isAction(annotation)) decorators[key] = M.action;
+    else decorators[key] = M.observable;
+  });
+
+  M.decorate(target, decorators);
+  return target;
+};

package/src/composer.ts

@@ -0,0 +1,82 @@
+import { FieldPropsEnum } from "./models/FieldProps";
+import { FormInterface } from "./models/FormInterface";
+
+export const composer = (forms: { [key in string]: FormInterface }) => {
+
+    const instances = (): { [key in string]: FormInterface } => forms;
+
+    const select = (key: string): FormInterface => forms[key];
+
+    const check = (prop: string): any => Object
+        .entries(forms)
+        .reduce((acc: Record<string, any>, entry: any) =>
+            Object.assign(acc, {
+                [entry[0]]: (entry[1] as FormInterface).check(prop)
+            }), {} as Record<string, any>);
+
+    const get = (prop: string): any => Object
+        .entries(forms)
+        .reduce((acc: Record<string, any>, entry: any) =>
+            Object.assign(acc, {
+                [entry[0]]: (entry[1] as FormInterface).get(prop)
+            }), {} as Record<string, any>);
+
+    const valid = () => (Object.values(check(FieldPropsEnum.isValid)) as boolean[])
+       .every((val: boolean) => val === true);
+
+    const error = () => (Object.values(check(FieldPropsEnum.hasError)) as boolean[])
+       .some((val: boolean) => val === true);
+
+    const clear = ({ deep = true, execHook = false }
+        : { deep?: boolean, execHook?: boolean } = {
+            deep: true, execHook: false,
+        }): void[] => Object.values(forms).map((form: FormInterface) => form.clear(deep, execHook));
+
+    const reset = ({ deep = true, execHook = false }
+        : { deep?: boolean, execHook?: boolean } = {
+            deep: true, execHook: false,
+        }): void[] => Object.values(forms).map((form: FormInterface) => form.reset(deep, execHook));
+
+    const validate = ({ showErrors = true }
+        : { showErrors?: boolean } = {
+            showErrors: true,
+        }): Promise<any> =>
+            Promise.all(Object.values(forms)
+                .map((form: FormInterface) => form.validate({ showErrors })))
+                .then(() => ({
+                    composer: composer(forms),
+                    valid: valid(),
+                    error: error(),
+                    errors: get('error'),
+                    values: get('value'),
+                }));
+
+    const submit = ({ validate = true, execOnSubmitHook = false, execValidationHooks = false }
+        : { validate?: boolean, execOnSubmitHook?: boolean, execValidationHooks?: boolean  } = {
+            validate: true, execOnSubmitHook: false, execValidationHooks: false,
+        }): Promise<any> =>
+            Promise.all(Object.values(forms)
+                .map((form: FormInterface) => form.submit({},
+                    { execOnSubmitHook, execValidationHooks , validate }
+                )))
+                .then(() => ({
+                    composer: composer(forms),
+                    valid: valid(),
+                    error: error(),
+                    errors: get('error'),
+                    values: get('value'),
+                }));
+
+    return {
+        instances,
+        select,
+        check,
+        get,
+        valid,
+        error,
+        validate,
+        submit,
+        clear,
+        reset,
+    }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+import Form from "./Form";
+import Field from "./Field";
+import ArrayMap from "./ArrayMap";
+
+export default Form;
+export { Form, Field, ArrayMap };
+export type { PathsOf, FieldDefinition } from "./models/FormInterface";

package/src/models/BaseInterface.ts

@@ -0,0 +1,45 @@
+import { SharedActionsInterface } from "./SharedActionsInterface";
+import { SharedEventsInterface } from "./SharedEventsInterface";
+import { SharedHelpersInterface } from "./SharedHelpersInterface";
+import { SharedInitializerInterface } from "./SharedInitializerInterface";
+import { SharedUtilsInferface } from "./SharedUtilsInterface";
+import { StateInterface } from "./StateInterface";
+import ArrayMap from "../ArrayMap";
+export interface BaseInterface<F extends Record<string, any> = Record<string, any>>
+  extends SharedInitializerInterface,
+    SharedActionsInterface,
+    SharedEventsInterface,
+    SharedUtilsInferface,
+    SharedHelpersInterface<F> {
+  state: StateInterface;
+  fields: ArrayMap;
+  path: string | undefined | null;
+  $hooks: any;
+  $handlers: any;
+  $submitted: number;
+  $submitting: boolean;
+  $validated: number;
+  $validating: boolean;
+  $touched: boolean;
+  $changed: number;
+  changed: number;
+  submitted: number;
+  submitting: boolean;
+  validated: number;
+  validating: boolean;
+  hasIncrementalKeys: boolean;
+  hasNestedFields: boolean;
+  size: number;
+  execHook(name: string, fallback?: any, ...args: any[]): any;
+  execHandler(name: string, args: any, fallback?: any): any;
+  intercept(opt: any): any;
+  observe(opt: any): any;
+  onClear(args: any): any;
+  onReset(args: any): any;
+  onSubmit(args: any): any;
+  onAdd(args: any): any;
+  onDel(args: any): any;
+  firstError(): string | null;
+}
+
+export default BaseInterface;

package/src/models/BindingsInterface.ts

@@ -0,0 +1,25 @@
+import Bindings from "../Bindings";
+import { FieldPropsEnum, FieldPropsType } from "./FieldProps";
+
+export interface BindingsInterface {
+  templates: {
+    [index: string]: {
+      [key: string]: ({ field, props, keys }: any) => any;
+    };
+  };
+  rewriters: {
+    [index: string]: {
+      [key: string]: FieldPropsEnum;
+    };
+  };
+
+  load: (
+    field: any,
+    name: string,
+    props: FieldPropsType
+  ) => FieldPropsType;
+
+  register: (bindings: FieldPropsType) => Bindings;
+}
+
+export default BindingsInterface;

package/src/models/FieldInterface.ts

@@ -0,0 +1,97 @@
+import {BaseInterface} from "./BaseInterface";
+import {OptionsModel} from "./OptionsModel";
+import {StateInterface} from "./StateInterface";
+export interface FieldInterface<T = any> extends BaseInterface {
+  incremental: boolean;
+  hasInitialNestedFields: boolean;
+  id: string | undefined;
+  key: string | undefined;
+  name: string | undefined;
+  options: OptionsModel | undefined;
+  type: string | undefined;
+  label: string | undefined;
+  placeholder: string | undefined;
+  extra: Record<string, any>;
+  errorSync: string | null;
+  errorAsync: string | null;
+  validationErrorStack: string[];
+  validationFunctionsData: any[];
+  validationAsyncData: { valid: boolean, message: string | null };
+  debouncedValidation: any;
+  autoFocus: boolean;
+  inputMode: string;
+  ref: any;
+  showError: boolean;
+  checkValidationErrors: boolean;
+  checked: T | undefined;
+  value: T;
+  initial: T;
+  default: T;
+  actionRunning: boolean;
+  bindings: any;
+  disabled: boolean;
+  related: string[] | undefined;
+  rules: string[] | undefined;
+  validators: any[] | undefined;
+  validatedValue: any;
+  error: string | null;
+  hasError: boolean;
+  isValid: boolean;
+  isDefault: boolean;
+  isDirty: boolean;
+  isPristine: boolean;
+  isEmpty: boolean;
+  resetting: boolean;
+  clearing: boolean;
+  focused: boolean;
+  blurred: boolean;
+  touched: boolean;
+  deleted: boolean;
+  // handlers
+  onSync(args: any): any;
+  onChange(args: any): any;
+  onToggle(args: any): any;
+  onBlur(args: any): any;
+  onFocus(args: any): any;
+  onDrop(args: any): any;
+  onKeyDown(args: any): any;
+  onKeyUp(args: any): any;
+
+  // methods: {
+  setupField(
+    key: string,
+    path: string | undefined | null,
+    struct: string | undefined | null,
+    data: any,
+    props: any,
+    update: boolean
+  ): void;
+  getComputedProp(key: any): any;
+  // checkValidationPlugins(): void;
+  initNestedFields(field: any, update: boolean): void;
+  invalidate(message?: string, deep?: boolean, async?: boolean): void;
+  setValidationAsyncData(valid: boolean, message?: string|null): void;
+  resetValidation(deep: boolean): void;
+  clear(deep?: boolean): void;
+  reset(deep?: boolean): void;
+  focus(): void;
+  showErrors(show?: boolean, deep?: boolean): void;
+  observeValidationOnBlur(): void;
+  observeValidationOnChange(): void;
+  disposeValidationOnBlur(): void;
+  disposeValidationOnChange(): void;
+  initMOBXEvent(type: string): void;
+  bind(props?: any): any;
+}
+
+export interface FieldConstructor {
+  key: string;
+  path?: string;
+  struct?: string;
+  data?: any;
+  props?: any;
+  update?: boolean;
+  state: StateInterface;
+}
+
+export default FieldInterface;

package/src/models/FieldProps.ts

@@ -0,0 +1,116 @@
+export enum FieldPropsEnum {
+  key = "key",
+  id = "id",
+  path = "path",
+  name = "name",
+  fields = "fields",
+  ref= "ref",
+  type = "type",
+  computed = "computed",
+  value = "value",
+  initial = "initial",
+  default = "default",
+  checked = "checked",
+  label = "label",
+  placeholder = "placeholder",
+  error = "error",
+  validatedWith = "validatedWith",
+  validators = "validators",
+  rules = "rules",
+  related = "related",
+  options = "options",
+  extra = "extra",
+  bindings = "bindings",
+  hooks = "hooks",
+  handlers = "handlers",
+  converter="converter",
+  input="input",
+  output="output",
+  interceptors = "interceptors",
+  observers = "observers",
+  // computed
+  disabled = "disabled",
+  deleted = "deleted",
+  blurred = "blurred",
+  validating = "validating",
+  submitting = "submitting",
+  clearing = "clearing",
+  resetting = "resetting",
+  changed = "changed",
+  touched = "touched",
+  focused = "focused",
+  isEmpty = "isEmpty",
+  isDefault = "isDefault",
+  isPristine = "isPristine",
+  isDirty = "isDirty",
+  isValid = "isValid",
+  hasError = "hasError",
+  // handlers
+  onInit = "onInit",
+  onSync = "onSync",
+  onChange = "onChange",
+  onBlur = "onBlur",
+  onFocus = "onFocus",
+  onToggle = "onToggle",
+  onDrop = "onDrop",
+  onSubmit = "onSubmit",
+  onReset = "onReset",
+  onClear = "onClear",
+  onAdd = "onAdd",
+  onDel = "onDel",
+  autoFocus = "autoFocus",
+  inputMode = "inputMode",
+  onKeyDown = "onKeyDown",
+  onKeyUp = 'onKeyUp',
+  class = "class",
+  nullable = "nullable",
+  autoComplete = "autoComplete",
+}
+
+export type FieldPropsType = {
+  [key in FieldPropsEnum]?: any;
+}
+
+export enum AllowedFieldPropsTypes {
+  computed = 'computed',
+  observable = 'observable',
+  editable = 'editable',
+  all = 'all',
+}
+
+export enum FieldPropsOccurrence {
+  some = 'some',
+  every = 'every',
+}
+
+export enum SeparatedPropsMode {
+  computed = 'computed',
+  values = 'values',
+  labels = 'labels',
+  placeholders = 'placeholders',
+  defaults = 'defaults',
+  initials = 'initials',
+  disabled = 'disabled',
+  deleted = 'deleted',
+  types = 'types',
+  related = 'related',
+  rules = 'rules',
+  options = 'options',
+  bindings = 'bindings',
+  extra = 'extra',
+  hooks = 'hooks',
+  handlers = 'handlers',
+  validatedWith = 'validatedWith',
+  validators = 'validators',
+  observers = 'observers',
+  interceptors = 'interceptors',
+  converters = 'converters',
+  input = 'input',
+  output = 'output',
+  autoFocus = 'autoFocus',
+  inputMode = 'inputMode',
+  refs = 'refs',
+  classes = 'classes',
+  nullable = 'nullable',
+  autoComplete = 'autoComplete',
+}

package/src/models/FormInterface.ts

@@ -0,0 +1,203 @@
+import Field from "../Field";
+import { BaseInterface } from "./BaseInterface";
+import { FieldInterface, FieldConstructor } from "./FieldInterface";
+import { OptionsModel } from "./OptionsModel";
+import { ValidatorInterface, ValidationPlugins } from "./ValidatorInterface";
+/**
+ * Recursively derives all possible field paths from a form values type `T`.
+ * Supports nested objects, arrays (with `[]` suffix), and dot-separated paths.
+ * Excludes built-in non-plain objects like Date, File, Blob, etc.
+ *
+ * @example
+ * // --- Basic usage ---
+ * type Profile = {
+ *   username: string;
+ *   email: string;
+ * };
+ * // PathsOf<Profile> = "username" | "email"
+ *
+ * @example
+ * // --- Nested objects ---
+ * type NestedClubFields = {
+ *   club: { name: string; city: string };
+ *   members: { firstname: string; lastname: string; hobbies: string[] }[];
+ * };
+ * // PathsOf<NestedClubFields> = "club" | "members" | "club.name" | "club.city"
+ * //   | "members[].firstname" | "members[].lastname" | "members[].hobbies"
+ *
+ * @example
+ * // --- Usage with form.$() or form.select() ---
+ * const form = new Form<{ profile: { name: string; age: number } }>({  });
+ *
+ * // Top-level keys get autocomplete directly from keyof F:
+ * form.$('profile'); // ✓ autocomplete, returns Field<{ name: string; age: number }>
+ *
+ * // For nested paths, use PathsOf in a helper function:
+ * import { PathsOf } from 'mobx-formkit';
+ *
+ * function getField(form: Form<{ profile: { name: string; age: number } }>, path: PathsOf<{ profile: { name: string; age: number } }>) {
+ *   return form.$(path).value;
+ *   //        ^— path autocompletes to: "profile" | "profile.name" | "profile.age"
+ * }
+ * getField(form, 'profile.name'); // ✓ returns string
+ */
+export type PathsOf<T> = T extends (infer U)[]
+  ? PathsOf<U>
+  : T extends Date | File | Blob | RegExp | Map<any, any> | Set<any> | Promise<any>
+    ? never
+    : T extends object
+      ? { [K in keyof T & string]:
+          T[K] extends (infer U)[]
+            ? K | `${K}[].${PathsOf<U>}`
+            : T[K] extends object
+              ? K | `${K}.${PathsOf<T[K]>}`
+              : K
+        }[keyof T & string]
+      : never;
+
+export interface FormInterface<F extends Record<string, any> = Record<string, any>> extends BaseInterface<F> {
+  name: string;
+  extra: Record<string, any>;
+  validator: ValidatorInterface;
+  debouncedValidation: any;
+  // getters
+  flatMapValues: Record<string, any>;
+  clearing: boolean;
+  resetting: boolean;
+  error: string | null;
+  hasError: boolean;
+  isValid: boolean;
+  isPristine: boolean;
+  isDirty: boolean;
+  isDefault: boolean;
+  isEmpty: boolean;
+  focused: boolean;
+  touched: boolean;
+  disabled: boolean;
+  // methods
+  // init($fields: any): void;
+  invalidate(message?: string | null, deep?: boolean): void;
+  showErrors(show?: boolean): void;
+  clear(deep?: boolean, execHook?: boolean): void;
+  reset(deep?: boolean, execHook?: boolean): void;
+
+  makeField(data: FieldConstructor, FieldClass?: typeof Field): FieldInterface;
+
+  $(key: keyof F | PathsOf<F>): Field<F[keyof F]>;
+}
+
+export interface FieldDefinition {
+  /** Field value */
+  value?: any;
+  /** Field label */
+  label?: string;
+  /** Field placeholder */
+  placeholder?: string;
+  /** Validation rules string (e.g. "required|string|min:3") */
+  rules?: string;
+  /** Field type (e.g. "text", "checkbox", "password", "file", etc.) */
+  type?: string;
+  /** Whether the field is disabled */
+  disabled?: boolean;
+  /** Related field paths */
+  related?: string[];
+  /** Default value */
+  default?: any;
+  /** Initial value */
+  initial?: any;
+  /** Nested sub-fields definition */
+  fields?: any;
+  /** Binding name for the UI component */
+  bindings?: string;
+  /** Extra metadata */
+  extra?: Record<string, any>;
+  /** Field-level options */
+  options?: OptionsModel;
+  /** Field hooks */
+  hooks?: Record<string, any>;
+  /** Field handlers */
+  handlers?: Record<string, any>;
+  /** Custom validation functions */
+  validators?: any[];
+  /** Which field prop to use for validation output */
+  validatedWith?: string;
+  /** MobX observers */
+  observers?: any[];
+  /** MobX interceptors */
+  interceptors?: any[];
+  /** Ref callback/object */
+  ref?: any;
+  /** Whether the field is nullable */
+  nullable?: boolean;
+  /** Auto-focus on mount */
+  autoFocus?: boolean;
+  /** Input mode for mobile keyboards */
+  inputMode?: string;
+  /** Autocomplete attribute */
+  autoComplete?: string;
+  /** Input converter function */
+  input?: Function;
+  /** Output converter function */
+  output?: Function;
+  /** Value converter function */
+  converter?: Function;
+  /** Multiple converters */
+  converters?: Function[];
+  /** Computed value */
+  computed?: any;
+  /** Field name (overrides the key) */
+  name?: string;
+  /** Custom Field class */
+  class?: any;
+}
+
+export interface FieldsDefinitions {
+  struct?: string[];
+  /**
+   * Field definitions.
+   * - For autocomplete on field props, use `Record<string, FieldDefinition>`
+   *   (e.g. `const fields: Record<string, FieldDefinition> = { ... }`)
+   * - Or pass an array of field path strings for struct/separated mode.
+   */
+  fields?: any;
+  computed?: any;
+  values?: any;
+  labels?: any;
+  placeholders?: any;
+  defaults?: any;
+  initials?: any;
+  disabled?: any;
+  deleted?: any;
+  types?: any;
+  related?: any;
+  rules?: any;
+  options?: any;
+  bindings?: any;
+  extra?: any;
+  hooks?: any;
+  handlers?: any;
+  validatedWith?: any;
+  validators?: any;
+  observers?: any;
+  interceptors?: any;
+  input?: any;
+  output?: any;
+  autoFocus?: any;
+  inputMode?: any;
+  refs?: any;
+  classes?: Record<string, any>;
+  nullable?: any;
+  converters?: any;
+}
+
+export interface FormConfig {
+  name?: string;
+  options?: OptionsModel;
+  plugins?: ValidationPlugins;
+  bindings?: Record<string, any>;
+  hooks?: Record<string, any>;
+  handlers?: Record<string, any>;
+  extra?: Record<string, any>;
+}
+
+export default FormInterface;

package/src/models/OptionsInterface.ts

@@ -0,0 +1,9 @@
+import {OptionsModel} from "./OptionsModel";
+
+export interface OptionsInterface {
+  options: OptionsModel;
+  get: (key: string, instance?: any) => any;
+  set: (options: OptionsModel) => void;
+}
+
+export default OptionsInterface;