feat: add FieldDefinition interface and PathsOf utility type for field props and path autocomplete

Author: foxhound87

CHANGELOG.md

@@ -4,6 +4,11 @@
 - feat: enable strictNullChecks across all source files
 - fix: resolve all noImplicitAny errors across source files
 - chore: enable strictFunctionTypes, alwaysStrict, strictBindCallApply, noImplicitThis, useUnknownInCatchVariables, strictPropertyInitialization
+- feat: add `FieldDefinition` interface for autocomplete of field props in constructor
+- feat: add `PathsOf<T>` recursive utility type for nested field path inference
+- feat: override `select()` in `Form` with proper return type
+- feat: export `PathsOf` and `FieldDefinition` from package entry point
+- docs: improved JSDoc on `$()` and `PathsOf` with usage examples
 
 # 6.12.7 (master)
 
@@ -517,7 +522,7 @@ fix: #371 #399 #408
 - Introduced Form & Field `validating` mobx computed (async check).
 - Events Hooks: returned Form instance (was a Field instance).
 - Fixed Async error state (removed `loadingMessage`)
-- Fixed Async "validating..." Message (null as default).
+- Fixed Async \"validating...\" Message (null as default).
 - `loadingMessage` option removed.
 
 # 1.19
@@ -527,7 +532,7 @@ fix: #371 #399 #408
 - Better Array Handling.
 - Optional `submit()` onSuccess/onError callbacks.
 - Fixed Empty Array Handling in Field Container.
-- Removed Initial Array element "0" (no more del(0)).
+- Removed Initial Array element \"0\" (no more del(0)).
 
 # 1.18
 
@@ -547,7 +552,7 @@ fix: #371 #399 #408
 - Introduced form computed validating().
 - Introduced alwaysShowDefaultError option.
 - Introduced setup() method.
-- Introduced "disabled" computed prop
+- Introduced \"disabled\" computed prop
 - Introduced Fields Props Bindings
 - Introduced initial props: types, bindings.
 - Introduced field props: type, bindings.
@@ -594,67 +599,4 @@ fix: #371 #399 #408
 
 # 1.10
 
-- Fixed some documentation errors
-- Enabled VJF enhancement
-- Support for React Select
-
-# 1.9
-
-- Validation Plugins
-- Multiple Validation Styles
-- Support for Async Validation
-- Support for Material UI, React Widgets
-- Package name changed from `mobx-ajv-form` to `mobx-react-form`
-
-# 1.8
-
-- Decoupled validator from fields
-
-# 1.7
-
-- Validation using mobx observe on field $value
-- Display errors of related fields
-
-# 1.5
-
-- Custom Validation Functions
-
-# 1.4
-
-- Support for v5 json schema rules
-
-# 1.3
-
-- Updated constructor with single object
-- Custom Validation Keywords
-- Created API Documentation
-- Added methods: isDirty();
-- Renamed computed values: valid to isValid
-- Added some tests
-
-# 1.2
-
-- Added silent mode
-- Updated methods: validate(); clear(); reset();
-- Clear genericErrorMessage on clear/reset
-
-# 1.2
-
-- Added methods: reset();
-- Updated methods: clear();
-
-# 1.1
-
-- Fixed UMD build external libs
-
-# 1.1
-
-- Added UMD build/support
-
-# 1.1
-
-- Updated README.md
-
-# 1.0
-
-- First Release
+- Fix

src/Form.ts

@@ -182,10 +182,34 @@ export default class Form<F extends Record<string, any> = Record<string, any>> e
     return new FieldClass(data);
   }
 
+  /**
+   * Select a field by key with type inference.
+   * Provides autocomplete for field keys when the form is typed with a generic `F`.
+   *
+   * @example
+   * // Top-level keys get autocomplete from keyof F:
+   * form.$('username'); // returns Field<string>
+   *
+   * @example
+   * // For nested paths, use the `PathsOf` utility type:
+   * import { PathsOf } from 'mobx-react-form';
+   *
+   * function getField(form: Form<NestedClubFields>, path: PathsOf<NestedClubFields>) {
+   *   return form.$(path); // path autocompletes to "club" | "club.name" | "members[].firstname" | ...
+   * }
+   */
   override $(key: keyof 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] };
   }

src/index.ts

@@ -3,3 +3,4 @@ import Field from "./Field";
 
 export default Form;
 export { Form, Field };
+export type { PathsOf, FieldDefinition } from "./models/FormInterface";

src/models/FormInterface.ts

@@ -3,6 +3,58 @@ 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-react-form';
+ *
+ * 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>;
@@ -33,8 +85,79 @@ export interface FormInterface<F extends Record<string, any> = Record<string, an
   makeField(data: FieldConstructor, FieldClass?: typeof Field): FieldInterface;
 }
 
+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;