Form Engine

A framework-agnostic form state manager with React bindings, offering validation schemas, field registration, dirty/touched tracking, and dynamic field arrays.

AI Agent Quick Reference

Core Exports

| Export | Type | Description | | --------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------- | | FormCore | Class | Framework-neutral class managing form state, values, validations, and subscribers. | | useForm<TFieldValues>(options?: FormOptions): ReactFormResult | Hook | React wrapper hook to instantiate and bind a FormCore instance. | | useFieldArray(options: UseFieldArrayOptions) | Hook | React hook to manage dynamic array inputs (append, prepend, swap, remove, insert). | | Controller | Component | React wrapper component for custom/third-party inputs needing manual value mapping. |

Core Types & Signatures

• FormCore:
  • register(path: string, options?: RegisterOptions)
  • setValue(path: string, value: any)
  • getValues(): TFieldValues
  • getErrors(): Record<string, FieldError>
  • validateForm(): Promise<boolean>
  • handleSubmit(onValid: (data) => void, onInvalid?: (errors) => void)
  • getFieldArray(path: string): FieldArrayController
• RegisterOptions:
  • required?: boolean | string
  • min?: number | { value: number; message: string }
  • max?: number | { value: number; message: string }
  • pattern?: RegExp | { value: RegExp; message: string }
  • validate?: (value: any) => string | boolean | undefined | Promise<...>
  • Validator formats: email, url, numeric, integer, float, alpha, alphanumeric, semver, creditCard, date
  • Date boundaries: before: string, after: string

Basic Usage (React)

import { useForm } from "@azlib/form-engine";

function MyForm() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm({
    defaultValues: { name: "", email: "" },
    mode: "onBlur",
  });

  const onSubmit = (data) => console.log("Valid Submit:", data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("name", { required: "Name is required" })} />
      {errors.name && <span>{errors.name.message}</span>}

      <input
        {...register("email", { email: "Must be a valid email address" })}
      />
      {errors.email && <span>{errors.email.message}</span>}

      <button type="submit">Submit</button>
    </form>
  );
}

Dynamic Field Arrays

import { useForm, useFieldArray } from "@azlib/form-engine";

function TaskList() {
  const { control, register, handleSubmit } = useForm({
    defaultValues: { tasks: [{ title: "Task 1" }] },
  });

  const { fields, append, remove } = useFieldArray({
    control,
    name: "tasks",
  });

  return (
    <div>
      {fields.map((field, index) => (
        <div key={field.id}>
          <input {...register(`tasks.${index}.title`)} />
          <button onClick={() => remove(index)}>Remove</button>
        </div>
      ))}
      <button onClick={() => append({ title: "New Task" })}>Add Task</button>
    </div>
  );
}

Behavioral Gotchas

• Path Syntax: Supports dot-notation paths for accessing nested properties (e.g. users.0.email).
• Server Errors Reset: If the form contains errors marked with type "server", they are automatically cleared as soon as the corresponding field triggers an onChange event.
• Async Validation: Custom field validate functions can return a Promise, causing formState.isValidating to toggle true during execution.