@explita/formly 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.2] - 2026-01-16
+
+### Added
+
+- **Field Arrays**: Full support for dynamic lists with a comprehensive API (`push`, `insert`, `remove`, `swap`, `move`, `moveUp`, `moveDown`, etc.).
+- **Form persistence (Drafts)**: Built-in support for saving and restoring form progress locally using `persistKey`.
+- **Computed Fields**: Support for fields that derive their value from other fields, including wildcard support for arrays (`array.*.field`).
+- **Form Registry**: Ability to access and control any form instance globally by its unique ID.
+- **Improved Performance**: Switched to a flat-state internal representation with precise pub/sub notifications to minimize re-renders.
+- **Deep Path Utilities**: Enhanced handling of nested objects and arrays in form state.
+
+### Changed
+
+- Refactored internal state Management for better scalability and performance.
+- Simplified `useForm` initialization logic.
+
+## [0.1.1] - 2026-01-11
+
+### Fixed
+
+- Initial maintenance and stabilization improvements.
+
+## [0.1.0] - 2026-01-11
+
+### Added
+
+- Initial release of `@explita/formly`.
+- **Core Hooks**:
+  - `useForm`: Core hook for form state management, validation, and submission.
+  - `useField`: Hook for managing individual field state and interactions.
+  - `useFormContext`: Hook for accessing form state within the `Form` provider.
+  - `useFormById`: Utility hook to access a form instance globally by its ID.
+- **Components**:
+  - `Form`: Provider component for the form context.
+  - `Field`: Declarative component for field management.
+  - `FieldError`: Component for displaying field validation messages.
+  - `FormSpy`: Component to monitor form state changes without triggering global re-renders.
+  - `Label`: Accessible label component integrated with form field state.
+- **Validation**:
+  - First-class support for `zod` schema validation.
+- **Features**:
+  - Support for complex, nested data structures.
+  - Optimized performance through precise subscription-based updates.
+  - Fully type-safe API for form values, errors, and handlers.

package/dist/hooks/use-form-initialization.d.ts

@@ -0,0 +1,2 @@
+import { UseFormInitializationProps } from "../types/utils";
+export declare function useFormInitialization({ defaultValues, persistKey, savedFormFirst, generatePlaceholders, computed, draftListeners, compute, onReady, setValues, createHandlerContext, }: UseFormInitializationProps): void;

package/dist/hooks/use-form-initialization.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFormInitialization = useFormInitialization;
+const array_helpers_1 = require("../lib/array-helpers");
+const utils_1 = require("../lib/utils");
+const react_1 = require("react");
+const utils_2 = require("../utils");
+function useFormInitialization({ defaultValues, persistKey, savedFormFirst, generatePlaceholders, computed, draftListeners, compute, onReady, setValues, createHandlerContext, }) {
+    const previousDefaultValuesRef = (0, react_1.useRef)({});
+    const hasInitializedRef = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        var _a, _b;
+        const saved = persistKey
+            ? (0, utils_2.readDraft)(persistKey)
+            : {};
+        const merged = (0, utils_1.mergeInitialValues)({
+            saved,
+            defaults: defaultValues,
+            savedFormFirst,
+            generatePlaceholders,
+        });
+        const flattenedDefaults = (0, utils_1.flattenFormValues)(defaultValues);
+        const defaultsUnchanged = (0, utils_1.shallowEqual)(previousDefaultValuesRef.current, flattenedDefaults);
+        if (defaultsUnchanged)
+            return;
+        previousDefaultValuesRef.current = flattenedDefaults;
+        if (!hasInitializedRef.current) {
+            // Restore persisted state
+            (_b = (_a = draftListeners.current).restore) === null || _b === void 0 ? void 0 : _b.call(_a, merged);
+            // Notify readiness
+            onReady === null || onReady === void 0 ? void 0 : onReady(merged, createHandlerContext(merged));
+            hasInitializedRef.current = true;
+        }
+        // Run computed fields
+        if (computed) {
+            for (const key in computed) {
+                const { deps, fn } = computed[key];
+                if (key.includes("*")) {
+                    const parts = key.split("*");
+                    if (parts.length !== 2)
+                        continue;
+                    const [arrayName, fieldName] = parts;
+                    const arrLength = (0, array_helpers_1.getArrayKeys)(arrayName, merged).length;
+                    for (let i = 0; i < arrLength; i++) {
+                        const computedKey = `${arrayName}.${i}.${fieldName}`;
+                        const fieldDeps = (0, array_helpers_1.extraxtArrayPrefixies)(arrayName, i, deps);
+                        compute(computedKey, fieldDeps, (vals) => fn(vals, i));
+                    }
+                }
+                else {
+                    compute(key, deps || [], fn);
+                }
+            }
+        }
+        // Commit values as source of truth
+        setValues({ ...merged }, { overwrite: true }, true);
+    }, [defaultValues]);
+}

package/dist/hooks/use-form.d.ts

@@ -1,43 +1,3 @@
 import type { z } from "zod";
 import { FormInstance, FormValues } from "../types/utils";
-/**
- * useForm is a React hook that allows you to manage form state and validation.
- *
- * @param schema - a Zod schema object that defines the form structure and validation rules.
- * @param defaultValues - an object containing the default values for the form fields.
- * @param errors - an object containing the initial errors for the form fields.
- * @param mode - the form mode, either "controlled" or "uncontrolled".
- * @param errorParser - a function that takes an error and returns a string to be displayed to the user.
- * @param persistKey - a string that defines the key under which the form state is persisted.
- * @param check - a function that takes the form values and an object containing the focus method for each field.
- * @param onSubmit - a function that takes the form values and an object containing the focus method for each field.
- * @param persistKey - a string that defines the key under which the form state is persisted.
- * @param computed - an object containing the computed fields.
- * @param autoFocusOnError - a boolean that defines whether to focus on the first error field.
- * @param savedFormFirst - a boolean that defines whether to prioritize the saved form state.
- * @param validateOn - a string that defines when to validate the form.
- *
- * @returns an object containing the useForm API methods.
- *
- * @example
- * const form = useForm({
- *   schema,
- *   defaultValues,
- *   errors,
- *   mode,
- *   errorParser,
- *   persistKey,
- *   check,
- *   onSubmit: async(values)=>{}
- * });
- *
- * <Form use={form}>
- *   {formFields.map((field) => (
- *     <div key={field.name}>
- *       <label>{field.label}</label>
- *       <input type="text" {...register(field.name)} />
- *     </div>
- *   ))}
- * </Form>
- */
 export declare function useForm<TSchema extends z.ZodObject<any> | undefined = undefined, TDefault = TSchema extends z.ZodObject<any> ? z.infer<TSchema> : Record<string, any>>(options?: FormValues<TSchema, TDefault>): FormInstance<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : TDefault>;

package/dist/hooks/use-form.js

@@ -12,46 +12,8 @@ const group_helpers_1 = require("../lib/group-helpers");
 const components_1 = require("../components");
 const pub_sub_1 = require("../lib/pub-sub");
 const form_registry_1 = require("../lib/form-registry");
-/**
- * useForm is a React hook that allows you to manage form state and validation.
- *
- * @param schema - a Zod schema object that defines the form structure and validation rules.
- * @param defaultValues - an object containing the default values for the form fields.
- * @param errors - an object containing the initial errors for the form fields.
- * @param mode - the form mode, either "controlled" or "uncontrolled".
- * @param errorParser - a function that takes an error and returns a string to be displayed to the user.
- * @param persistKey - a string that defines the key under which the form state is persisted.
- * @param check - a function that takes the form values and an object containing the focus method for each field.
- * @param onSubmit - a function that takes the form values and an object containing the focus method for each field.
- * @param persistKey - a string that defines the key under which the form state is persisted.
- * @param computed - an object containing the computed fields.
- * @param autoFocusOnError - a boolean that defines whether to focus on the first error field.
- * @param savedFormFirst - a boolean that defines whether to prioritize the saved form state.
- * @param validateOn - a string that defines when to validate the form.
- *
- * @returns an object containing the useForm API methods.
- *
- * @example
- * const form = useForm({
- *   schema,
- *   defaultValues,
- *   errors,
- *   mode,
- *   errorParser,
- *   persistKey,
- *   check,
- *   onSubmit: async(values)=>{}
- * });
- *
- * <Form use={form}>
- *   {formFields.map((field) => (
- *     <div key={field.name}>
- *       <label>{field.label}</label>
- *       <input type="text" {...register(field.name)} />
- *     </div>
- *   ))}
- * </Form>
- */
+const use_form_initialization_1 = require("./use-form-initialization");
+const meta_context_1 = require("../lib/meta-context");
 function useForm(options) {
     var _a;
     const { schema, validateOn = "change-submit", defaultValues = {}, errors = {}, mode = "controlled", errorParser, check, computed, onSubmit, onReady, autoFocusOnError = true, savedFormFirst = true, id, } = options || {};
@@ -93,6 +55,7 @@ function useForm(options) {
     // optional: track unregister for each field
     const unregisteredRef = (0, react_1.useRef)({});
     const visibilitySubscribersRef = (0, react_1.useRef)({});
+    const previousErrorsRef = (0, react_1.useRef)({});
     // placeholders
     const generatePlaceholders = (0, react_1.useMemo)(() => {
         if (mode === "controlled")
@@ -127,36 +90,13 @@ function useForm(options) {
     }, [schema]);
     //set errors on errors change
     (0, react_1.useEffect)(() => {
+        const flattenedErrors = (0, utils_2.flattenFormValues)(errors);
+        const errorsUnchanged = (0, utils_2.shallowEqual)(previousErrorsRef.current, flattenedErrors);
+        if (errorsUnchanged)
+            return;
+        previousErrorsRef.current = flattenedErrors;
         setErrors(errors);
-    }, []);
-    //set default values on mount
-    (0, react_1.useEffect)(() => {
-        var _a, _b;
-        const saved = persistKey ? (0, utils_1.readDraft)(persistKey) : {};
-        const primary = savedFormFirst ? saved : defaultValues;
-        const secondary = savedFormFirst ? defaultValues : saved;
-        const merged = (0, utils_2.mergeValues)((0, utils_2.mergeValues)(primary || {}, secondary || {}), generatePlaceholders);
-        (_b = (_a = draftListeners.current).restore) === null || _b === void 0 ? void 0 : _b.call(_a, merged);
-        onReady === null || onReady === void 0 ? void 0 : onReady(merged);
-        if (computed) {
-            for (const key in computed) {
-                const { deps, fn } = computed[key];
-                if (key.includes("*")) {
-                    const [arrayName, fieldName] = key.split("*");
-                    const arrLength = (0, array_helpers_1.getArrayKeys)(arrayName, merged).length;
-                    for (let i = 0; i < arrLength; i++) {
-                        const computedKey = `${arrayName}.${i}.${fieldName}`;
-                        const fieldDeps = (0, array_helpers_1.extraxtArrayPrefixies)(arrayName, i, deps);
-                        compute(computedKey, fieldDeps, (vals) => fn(vals, i));
-                    }
-                }
-                else {
-                    compute(key, deps || [], fn);
-                }
-            }
-        }
-        setValues({ ...merged }, { overwrite: true }, true);
-    }, [defaultValues]);
+    }, [errors]);
     // -----------------------------
     // Draft hooks
     // -----------------------------
@@ -769,6 +709,17 @@ function useForm(options) {
     const markDirty = (0, react_1.useCallback)((name) => {
         dirtyFieldsRef.current[name] = true;
     }, []);
+    function createHandlerContext(data) {
+        return {
+            setValues,
+            setErrors,
+            mapErrors: (errors, path) => setErrors((0, utils_2.mapErrors)(errors, path)),
+            reset,
+            focus,
+            array: (path) => (0, array_helpers_1.handlerArrayHelpers)(path, data),
+            meta: formMetadata,
+        };
+    }
     const handleSubmit = (0, react_1.useCallback)((onValid) => {
         return async (event) => {
             if (event)
@@ -779,15 +730,8 @@ function useForm(options) {
                     return;
                 setIsSubmitting(true);
                 const data = structuredClone(validatedData);
-                await onValid(validatedData, {
-                    setValues,
-                    setErrors,
-                    mapErrors: (errors, path) => setErrors((0, utils_2.mapErrors)(errors, path)),
-                    reset,
-                    focus,
-                    //@ts-ignore
-                    array: (path) => (0, array_helpers_1.handlerArrayHelpers)(path, data),
-                });
+                //@ts-ignore
+                await onValid(validatedData, createHandlerContext(data));
             }
             finally {
                 setIsSubmitting(false);
@@ -871,29 +815,24 @@ function useForm(options) {
             },
         };
     }, []);
-    const formMetadata = {
-        get(key) {
-            return metaRef.current.get(key);
-        },
-        set(key, value) {
-            metaRef.current.set(key, value);
-        },
-        delete(key) {
-            metaRef.current.delete(key);
-        },
-        has(key) {
-            return metaRef.current.has(key);
-        },
-        keys() {
-            return metaRef.current.keys();
-        },
-        values() {
-            return metaRef.current.values();
-        },
-        clear() {
-            metaRef.current.clear();
-        },
-    };
+    const formMetadata = (0, meta_context_1.createMetaContext)(metaRef, triggerRerender);
+    //initialize form
+    // Intentionally depends only on defaultValues.
+    // Draft restoration & computed logic are internally guarded.
+    (0, use_form_initialization_1.useFormInitialization)({
+        //@ts-ignore
+        defaultValues,
+        persistKey,
+        savedFormFirst,
+        generatePlaceholders,
+        //@ts-ignore
+        computed,
+        draftListeners,
+        onReady,
+        setValues,
+        createHandlerContext,
+        compute,
+    });
     const values = {
         register,
         validate: async () => {
@@ -929,8 +868,8 @@ function useForm(options) {
         get errors() {
             return getErrors();
         },
-        isSubmitting,
-        isValidated,
+        submitting: isSubmitting,
+        validated: isValidated,
         isDirty,
         markDirty,
         isTouched,

package/dist/lib/meta-context.d.ts

@@ -0,0 +1,11 @@
+export declare function createMetaContext(metaRef: React.RefObject<Map<string, unknown>>, triggerRerender: () => void): {
+    get<T = unknown>(key: string): T | undefined;
+    set(key: string, value: unknown, opts?: {
+        silent?: boolean;
+    }): void;
+    delete(key: string): void;
+    has(key: string): boolean;
+    keys(): MapIterator<string>;
+    values(): MapIterator<unknown>;
+    clear(): void;
+};

package/dist/lib/meta-context.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMetaContext = createMetaContext;
+function createMetaContext(metaRef, triggerRerender) {
+    return {
+        get(key) {
+            return metaRef.current.get(key);
+        },
+        set(key, value, opts) {
+            metaRef.current.set(key, value);
+            if (!(opts === null || opts === void 0 ? void 0 : opts.silent))
+                triggerRerender();
+        },
+        delete(key) {
+            metaRef.current.delete(key);
+        },
+        has(key) {
+            return metaRef.current.has(key);
+        },
+        keys() {
+            return metaRef.current.keys();
+        },
+        values() {
+            return metaRef.current.values();
+        },
+        clear() {
+            metaRef.current.clear();
+        },
+    };
+}

package/dist/lib/utils.d.ts

@@ -15,3 +15,10 @@ export declare function flattenFormValues<T extends any>(obj: T, prefix?: string
 export declare function nestFormValues<T extends any>(flat: T): T;
 export declare function mergeValues<T extends any>(defaultValues: T, saved: T): T;
 export declare function determineDirtyFields<T extends any>(defaultValues: T, saved: T): T;
+export declare function shallowEqual(a: Record<string, any>, b: Record<string, any>): boolean;
+export declare function mergeInitialValues({ saved, defaults, savedFormFirst, generatePlaceholders, }: {
+    saved: Record<string, any>;
+    defaults: Record<string, any>;
+    generatePlaceholders: Record<string, any>;
+    savedFormFirst?: boolean;
+}): Record<string, any>;

package/dist/lib/utils.js

@@ -7,6 +7,8 @@ exports.flattenFormValues = flattenFormValues;
 exports.nestFormValues = nestFormValues;
 exports.mergeValues = mergeValues;
 exports.determineDirtyFields = determineDirtyFields;
+exports.shallowEqual = shallowEqual;
+exports.mergeInitialValues = mergeInitialValues;
 /**
  * Combines multiple class names into a single string.
  * This function takes an array of class names and returns a single string
@@ -188,3 +190,13 @@ function determineDirtyFields(defaultValues, saved) {
     }
     return result;
 }
+function shallowEqual(a, b) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    return aKeys.length === bKeys.length && aKeys.every((k) => a[k] === b[k]);
+}
+function mergeInitialValues({ saved, defaults, savedFormFirst, generatePlaceholders, }) {
+    const primary = savedFormFirst ? saved : defaults;
+    const secondary = savedFormFirst ? defaults : saved;
+    return mergeValues(mergeValues(primary || {}, secondary || {}), generatePlaceholders);
+}

package/dist/types/utils.d.ts

@@ -62,16 +62,31 @@ export type HandlerContext<T> = {
     reset: () => void;
     focus: (name: Path<T>) => void;
     array: <P extends Path<T>>(path: P) => HandlerArrayHelpers<ArrayItem<T, P>>;
+    meta: FormMeta;
+};
+type ReadyContext<T> = {
+    meta: FormMeta;
+};
+export type FormMeta = {
+    get<T = unknown>(key: string): T | undefined;
+    set: (key: string, value: unknown, options?: {
+        silent?: boolean;
+    }) => void;
+    delete: (key: string) => void;
+    has: (key: string) => boolean;
+    keys: () => MapIterator<string>;
+    values: () => MapIterator<unknown>;
+    clear: () => void;
 };
 export type FormInstance<T> = {
     /**
      * Indicates whether the form is currently submitting.
      */
-    isSubmitting: boolean;
+    submitting: boolean;
     /**
      * Indicates whether the form is validated.
      */
-    isValidated: boolean;
+    validated: boolean;
     /**
      * Retrieves the current values of the form.
      */
@@ -240,29 +255,50 @@ export type FormInstance<T> = {
     };
     Field: typeof Field<T>;
     channel: ReturnType<typeof createFormBus<T>>["channel"];
-    meta: {
-        get<T = unknown>(key: string): T | undefined;
-        set: (key: string, value: unknown) => void;
-        delete: (key: string) => void;
-        has: (key: string) => boolean;
-        keys: () => MapIterator<string>;
-        values: () => MapIterator<unknown>;
-        clear: () => void;
-    };
+    meta: FormMeta;
 };
 export type SetValues<T> = (values: Partial<T>, options?: {
     overwrite?: boolean;
 }) => void;
 export type SetErrors<T> = (errors?: Partial<Record<Path<T>, string>> | z.ZodError["issues"]) => void;
 export type FormOptions<TSchema extends ZodObject<any> | undefined, TValues> = {
+    /**
+     * The schema to use for validation.
+     */
     schema?: TSchema;
+    /**
+     * The default values of the form.
+     */
     defaultValues?: TValues;
+    /**
+     * The errors of the form.
+     */
     errors?: Partial<Record<Path<SchemaType<TSchema, TValues>>, string>>;
+    /**
+     * The error parser to use for parsing errors.
+     */
     errorParser?: (message: string) => string;
+    /**
+     * The check function to use for checking the form.
+     */
     check?: CheckFn<SchemaType<TSchema, TValues>>;
+    /**
+     * The computed fields of the form.
+     */
     computed?: Record<string, Computed<SchemaType<TSchema, TValues>>>;
+    /**
+     * The submit handler of the form.
+     */
     onSubmit?: (values: SchemaType<TSchema, TValues>, ctx: HandlerContext<SchemaType<TSchema, TValues>>) => void;
-    onReady?: (values: SchemaType<TSchema, TValues>) => void;
+    /**
+     * Called when the form is ready/mounted.
+     */
+    onReady?: (values: SchemaType<TSchema, TValues>, ctx: ReadyContext<SchemaType<TSchema, TValues>>) => void;
+    /**
+     * The mode of the form.
+     *
+     * @default "uncontrolled"
+     */
     mode?: "controlled" | "uncontrolled";
     /**
      * The validation trigger.
@@ -274,8 +310,19 @@ export type FormOptions<TSchema extends ZodObject<any> | undefined, TValues> = {
      * Used to register the form so it can be accessed outside the hook.
      */
     id?: string;
+    /**
+     * The key used to persist the form state.
+     * If provided, the form state will be persisted to localStorage and restored on mount.
+     * If id is provided, it will be used as the key.
+     */
     persistKey?: string;
+    /**
+     * Whether to focus the first field with an error on submit.
+     */
     autoFocusOnError?: boolean;
+    /**
+     * Whether to use the saved form state first.
+     */
     savedFormFirst?: boolean;
 };
 type CheckFn<T> = (data: T, ctx: {
@@ -307,4 +354,23 @@ export type ConditionalConfig<T> = {
     then?: Partial<ConditionalEffects>;
     else?: Partial<ConditionalEffects>;
 };
+export type UseFormInitializationProps = {
+    defaultValues: Record<string, any>;
+    persistKey?: string;
+    savedFormFirst?: boolean;
+    generatePlaceholders: Record<string, any>;
+    computed?: Record<string, {
+        deps?: string[];
+        fn: (values: any, index?: number) => any;
+    }>;
+    compute: (key: string, deps: string[], fn: (values: any) => any) => void;
+    draftListeners: React.RefObject<{
+        restore?: (values: any) => void;
+    }>;
+    onReady?: (values: any, ctx: any) => void;
+    setValues: (values: Record<string, any>, options?: {
+        overwrite?: boolean;
+    }, silent?: boolean) => void;
+    createHandlerContext: (values: Record<string, any>) => any;
+};
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explita/formly",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A lightweight form toolkit for React built with developer ergonomics in mind. Includes a flexible Form component, `useForm`, `useField`, and `useFormContext` hooks for managing form state and validation with ease. Designed to simplify complex forms while remaining unopinionated and extensible.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -48,6 +48,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ]
 }

package/README.old.md

@@ -1,141 +0,0 @@
-⚠️ Using register() is convenient for quick input wiring, but for large forms where performance matters, prefer useField or Field to avoid unnecessary re-renders.
-
-For performance and clarity, here’s the usual pattern I’d recommend:
-
-<form.Field /> (from form instance) or standalone <Field />
-
-Best for most use cases.
-
-Handles binding, errors, and local reactivity automatically.
-
-Encapsulates the field logic, so the parent form doesn’t rerender on every change.
-
-Easy to drop into JSX and add labels, wrappers, or custom styling.
-
-useField() inside a separate component
-
-Great when you want full programmatic control over the field.
-
-Can wrap a custom input or a complex component.
-
-Keeps reactivity local to the component.
-
-Allows you to do more advanced things like computed values, conditional logic, or side effects specific to that field.
-
-✅ Rule of thumb:
-
-If you just need a simple form input, use <Field /> — minimal boilerplate, good defaults.
-
-If you need custom behavior or a completely custom component, wrap it with a component using useField().
-
-This way, the form itself stays light and doesn’t rerender unnecessarily, while each field manages its own state efficiently.
-
-# @explita/formly
-
-A powerful and extensible React form hook for building scalable forms with Zod validation, persistence, and full control.
-
-## ✨ Features
-
-- ✅ Built-in Zod schema validation
-- ✅ Controlled and uncontrolled modes
-- ✅ Persistent form state via `localStorage`
-- ✅ Field-level error handling and parsing
-- ✅ Debounced input validation
-- ✅ Works seamlessly with any UI library (e.g. shadcn/ui)
-
-## 📦 Installation
-
-```bash
-npm install @explita/formly
-# or
-yarn add @explita/formly
-# or
-pnpm add @explita/formly
-```
-
-## 🧪 Usage
-
-```tsx
-import { z } from "zod";
-import { useForm, Form, Field } from "@explita/formly";
-import { Input } from "@/components/ui/input";
-
-const schema = z.object({
-  email: z.email({ error: "Invalid email" }),
-  password: z
-    .string()
-    .min(6, { error: "Password must be at least 6 characters" }),
-});
-
-export default function LoginForm() {
-  const form = useForm({
-    schema,
-    defaultValues: { email: "", password: "" },
-    onSubmit: async (values) => {
-      console.log("Submitted", values);
-      // call server action here or perform an HTTP request
-      // const response = await login(values)
-      // return response
-      return values;
-    },
-    onSuccess: (result, ctx) => {
-      console.log("Success", result);
-      // result is the result of onSubmit
-      // ctx.reset(); - reset the form, you don't need this if resetOnSuccess is true
-    },
-    onError: (error, ctx) => {
-      console.log("Error", error, ctx);
-      // error - the error object (usually from schema or server)
-      // ctx.setErrors({ email: "Email is required" }); - useful for server errors
-    },
-    persistKey: "login-form", // Optional – saves input across reloads
-    errorParser: (msg) => msg, // Optional – customize error messages
-    mode: "controlled", // Optional – "controlled" is the default
-    resetOnSuccess: true, // Optional – clears the form on success
-  });
-
-  //Field meta is an object that contains the value, error, and hasError properties
-
-  return (
-    <Form use={form}>
-      <Field name="email" label="Email" isRequired>
-        {(props, meta) => <Input {...props} />}
-      </Field>
-
-      <Field name="password" label="Password" isRequired>
-        {(props, meta) => <Input type="password" {...props} />}
-      </Field>
-
-      <button type="submit" disabled={form.isSubmitting}>
-        Submit
-      </button>
-    </Form>
-  );
-}
-```
-
-## 🧩 API Overview
-
-### `useForm(options)`
-
-| Option           | Type                                  | Description                                 |
-| ---------------- | ------------------------------------- | ------------------------------------------- |
-| `schema`         | `ZodObject`                           | Optional Zod schema for validation          |
-| `defaultValues`  | `Partial<T>`                          | Initial form values                         |
-| `onSubmit`       | `(values, formData) => Promise<void>` | Async submission handler                    |
-| `onSuccess`      | `(result) => void`                    | Called on successful submission             |
-| `onError`        | `(error, ctx) => void`                | Called on error, with access to `setErrors` |
-| `persistKey`     | `string`                              | Key to store form values under              |
-| `errorParser`    | `(msg: string) => string`             | Optional formatter for error messages       |
-| `mode`           | `controlled`\|`uncontrolled`          | Default to controlled                       |
-| `resetOnSuccess` | `boolean`                             | Clear the form on successful submission     |
-
-### `useFormContext()`
-
-Can be used in any component nested inside the `Form` component to access the form context.
-
-##
-
-### 📄 License
-
-MIT — Made with ❤️ by [Explita](https://explita.ng)