{form.errors.user.email}
} ``` --- ### Nested helpers All helpers work with nested paths: ```ts form.setValue("user.email", "test@example.com"); form.resetField("profile.address.street"); form.setTouched("user.email", true); form.setError("user.email", "Invalid email"); ``` --- ### Nested cross-field validation Cross-field validation works seamlessly with nested values: ```ts register("confirmPassword", { validate: (value, values) => value !== values.user.password ? "Passwords do not match" : undefined, }); ``` Nested validation follows the same rules: - Validation is explicit - Errors are assigned only to the field being validated - On submit, **all registered fields are validated** --- --- ## ๐งฉ Field Arrays (v0.6) Formora supports **basic field arrays** with `append` and `remove` helpers. Array fields use **dot-index paths** (e.g. `items.0.name`). Bracket syntax like `items[0].name` is intentionally not supported. ### Basic example ```tsx const form = useForm({ initialValues: { items: [{ name: "" }], }, validateOn: "submit", }); function addItem() { form.append("items", { name: "" }, { shouldTouch: true }); } function removeItem(i: number) { form.remove("items", i); } return ( ); ``` ### Behavior notes - `append(name, value)` adds an item to the end of the array. - `remove(name, index)` removes an item and **shifts** the array branch in `errors`, `touched`, and `validating`. - On submit, **all registered fields** (including array fields) are validated. ### Async validation & field arrays When removing an array item (e.g. `remove("items", index)`), Formora automatically **cancels and invalidates** any pending async validations for fields at or after the removed index. This prevents stale async results (from old indices) from attaching to shifted items after removal. **Example scenario:** - User types in `items.2.email` โ async validation starts - User removes `items.1` - `items.2.email` becomes `items.1.email` - Formora cancels the old async validation so it cannot overwrite the new field state --- ## ๐งฐ DX Helpers (v0.3) Formora provides a small set of **developer experience helpers** for common imperative form actions. ### `setValue(name, value, options?)` ```ts form.setValue("email", "test@example.com", { shouldTouch: true, shouldValidate: true, }); ``` Options: - `shouldTouch` โ marks the field as touched - `shouldValidate` โ runs sync + async validation immediately This does **not** depend on `validateOn` and is fully explicit. --- ### `reset()` Resets the entire form to its initial state: ```ts form.reset(); ``` This will: - restore `initialValues` - clear `errors`, `touched`, and `validating` - cancel any pending async validation #### Reset options You can control which parts of the form state are preserved during reset: ```ts form.reset({ keepErrors: true, keepTouched: true, keepDirty: true, keepValidating: true, }); ``` - `keepErrors` โ preserve validation errors - `keepTouched` โ preserve touched state - `keepDirty` โ preserve dirty state - `keepValidating` โ preserve async validating state (otherwise pending async is cancelled) > โน๏ธ By default, `reset()` clears **all meta state** and cancels pending async validation. --- ### `resetField(name)` Resets a single field: ```ts form.resetField("email"); ``` This will: - restore the fieldโs initial value - clear its error, touched, and validating state - cancel pending async validation for that field #### ResetField options ```ts form.resetField("email", { keepError: true, keepTouched: true, keepDirty: true, keepValidating: true, }); ``` - `keepError` โ preserve the field error - `keepTouched` โ preserve touched state for this field - `keepDirty` โ preserve dirty state for this field - `keepValidating` โ preserve async validating state for this field When async validation is not preserved, any pending async validation for this field is **cancelled and invalidated**. --- ### `setValues(partial, options?)` Set multiple field values at once: ```ts form.setValues( { email: "user@example.com", age: 25 }, { shouldTouch: true, shouldValidate: true, } ); ``` Options: - `shouldTouch` โ marks all provided fields as touched - `shouldValidate` โ validates only the provided fields - `bypassDebounce` โ if `true`, async validation runs immediately --- ### Error helpers ```ts form.setError("email", "Email already exists"); form.clearError("email"); form.clearErrors(); ``` These helpers are useful for: - server-side validation errors - manual error control --- ### Touched helpers ```ts form.setTouched("email", true); form.touchAll(); ``` - `setTouched(name, boolean)` manually toggles touched state - `touchAll()` marks all registered fields as touched ### `handleSubmit(onValid, onInvalid?)` ```tsx