@explita/formly 0.1.0 → 0.1.1

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,54 @@
+"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)({});
+    (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,
+        });
+        // 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));
+        const flattenedDefaults = (0, utils_1.flattenFormValues)(defaultValues);
+        const defaultsUnchanged = (0, utils_1.shallowEqual)(previousDefaultValuesRef.current, flattenedDefaults);
+        if (defaultsUnchanged)
+            return;
+        previousDefaultValuesRef.current = flattenedDefaults;
+        // 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,7 @@ 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");
 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 +54,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 +89,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 +708,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 +729,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);
@@ -875,8 +818,10 @@ function useForm(options) {
         get(key) {
             return metaRef.current.get(key);
         },
-        set(key, value) {
+        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);
@@ -894,6 +839,23 @@ function useForm(options) {
             metaRef.current.clear();
         },
     };
+    //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 +891,8 @@ function useForm(options) {
         get errors() {
             return getErrors();
         },
-        isSubmitting,
-        isValidated,
+        submitting: isSubmitting,
+        validated: isValidated,
         isDirty,
         markDirty,
         isTouched,

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,28 @@ export type HandlerContext<T> = {
     reset: () => void;
     focus: (name: Path<T>) => void;
     array: <P extends Path<T>>(path: P) => HandlerArrayHelpers<ArrayItem<T, P>>;
+    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,15 +252,7 @@ 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;
@@ -262,7 +266,7 @@ export type FormOptions<TSchema extends ZodObject<any> | undefined, TValues> = {
     check?: CheckFn<SchemaType<TSchema, TValues>>;
     computed?: Record<string, Computed<SchemaType<TSchema, TValues>>>;
     onSubmit?: (values: SchemaType<TSchema, TValues>, ctx: HandlerContext<SchemaType<TSchema, TValues>>) => void;
-    onReady?: (values: SchemaType<TSchema, TValues>) => void;
+    onReady?: (values: SchemaType<TSchema, TValues>, ctx: HandlerContext<SchemaType<TSchema, TValues>>) => void;
     mode?: "controlled" | "uncontrolled";
     /**
      * The validation trigger.
@@ -307,4 +311,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.1",
   "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",