@explita/formly 0.1.0

package/dist/hooks/use-form.js

@@ -0,0 +1,961 @@
+"use client";
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useForm = useForm;
+const react_1 = require("react");
+const utils_1 = require("../utils");
+const utils_2 = require("../lib/utils");
+const deep_path_1 = require("../lib/deep-path");
+const array_helpers_1 = require("../lib/array-helpers");
+const zod_helpers_1 = require("../lib/zod-helpers");
+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>
+ */
+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 || {};
+    const persistKey = (_a = options === null || options === void 0 ? void 0 : options.persistKey) !== null && _a !== void 0 ? _a : options === null || options === void 0 ? void 0 : options.id;
+    const channelBus = (0, react_1.useMemo)(() => (0, pub_sub_1.createFormBus)(), []);
+    // validation state
+    const [isValidated, setIsValidated] = (0, react_1.useState)(false);
+    const [isSubmitting, setIsSubmitting] = (0, react_1.useState)(false);
+    const [, forceRender] = (0, react_1.useState)(0);
+    // Draft listeners
+    const draftListeners = (0, react_1.useRef)({});
+    // values
+    const formValues = (0, react_1.useRef)({});
+    const computing = (0, react_1.useRef)(new Set());
+    const computedFieldsRef = (0, react_1.useRef)({});
+    // watched fields state (triggers re-renders)
+    const watchedFieldsRef = (0, react_1.useRef)(new Set());
+    // errors
+    const formErrors = (0, react_1.useRef)({});
+    // subscribers
+    const globalSubscribers = (0, react_1.useRef)(new Set());
+    const fieldSubscribersRef = (0, react_1.useRef)({});
+    const fieldRegistryRef = (0, react_1.useRef)({});
+    const fieldsTransformsRef = (0, react_1.useRef)(new Map());
+    const fieldsValidationsRef = (0, react_1.useRef)(new Map());
+    const metaRef = (0, react_1.useRef)(new Map());
+    const fieldErrorSubscribersRef = (0, react_1.useRef)({});
+    // store field refs
+    const fieldRefs = (0, react_1.useRef)({});
+    const pendingFields = new Set();
+    let notifyScheduled = false;
+    const dirtyFieldsRef = (0, react_1.useRef)({});
+    const touchedFieldsRef = (0, react_1.useRef)({});
+    const currentSchema = (0, react_1.useRef)(schema && (0, zod_helpers_1.isZodSchema)(schema) ? schema : undefined);
+    //conditionals
+    const conditionalRulesRef = (0, react_1.useRef)([]);
+    const hiddenFieldsRef = (0, react_1.useRef)({});
+    const requiredFieldsRef = (0, react_1.useRef)({});
+    // optional: track unregister for each field
+    const unregisteredRef = (0, react_1.useRef)({});
+    const visibilitySubscribersRef = (0, react_1.useRef)({});
+    // placeholders
+    const generatePlaceholders = (0, react_1.useMemo)(() => {
+        if (mode === "controlled")
+            return (0, utils_2.flattenFormValues)({
+                ...(0, zod_helpers_1.createEmptyValues)(currentSchema.current),
+                // ...defaultValues,
+            });
+        return {};
+    }, [mode, currentSchema, defaultValues]);
+    //validate on values change
+    (0, react_1.useEffect)(() => {
+        const handler = (0, utils_1.debounce)(() => {
+            formValidation().then(({ isValidated, formValues: values }) => {
+                setIsValidated(isValidated);
+                formValues.current = values;
+            });
+        }, 200);
+        handler();
+        return () => handler.cancel();
+    }, [formValues, currentSchema, mode]);
+    //set schema on schema change
+    (0, react_1.useEffect)(() => {
+        if (schema) {
+            if (!(0, zod_helpers_1.isZodSchema)(schema)) {
+                throw new Error("Schema is not a zod schema.");
+            }
+            else {
+                resetErrors();
+                currentSchema.current = schema;
+            }
+        }
+    }, [schema]);
+    //set errors on errors change
+    (0, react_1.useEffect)(() => {
+        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]);
+    // -----------------------------
+    // Draft hooks
+    // -----------------------------
+    const onDraftSave = (0, react_1.useCallback)((callback) => {
+        draftListeners.current.save = callback;
+    }, []);
+    const onDraftRestore = (0, react_1.useCallback)((callback) => {
+        draftListeners.current.restore = callback;
+    }, []);
+    const writeDraftDebounced = (0, react_1.useCallback)((channel) => {
+        var _a, _b;
+        if (!persistKey)
+            return () => { };
+        (_b = (_a = draftListeners.current).save) === null || _b === void 0 ? void 0 : _b.call(_a, formValues.current);
+        if (channel === "immediate") {
+            return (0, utils_1.writeDraftImmediate)(persistKey, (0, utils_2.nestFormValues)(formValues.current));
+        }
+        return (0, utils_1.writeDraft)(persistKey, (0, utils_2.nestFormValues)(formValues.current));
+    }, [persistKey]);
+    const setSchema = (0, react_1.useCallback)((newSchema) => {
+        currentSchema.current = newSchema;
+    }, []);
+    function triggerRerender() {
+        forceRender((prev) => prev + 1);
+    }
+    const setValue = (0, react_1.useCallback)((name, value, opts = {}) => {
+        if (mode === "uncontrolled")
+            return;
+        value = applyTransformations(name, value);
+        // Always update ref for consistency
+        formValues.current[name] = value;
+        markDirty(name);
+        if (!opts.silent) {
+            channelBus.channel("value:*").emit(getValues());
+            channelBus.channel(`value:${name}`).emit(value);
+            if (!computedFieldsRef.current[name] &&
+                (validateOn === "change-submit" || validateOn === "change")) {
+                validateField(name, value);
+            }
+            const validator = fieldsValidationsRef.current.get(name);
+            if (validator) {
+                const error = validator(value);
+                setFieldError(name, error);
+            }
+            // 🔔 Notify subscribers
+            notifySubscribers(name);
+            // Update state if field is watched (triggers re-render)
+            if (watchedFieldsRef.current.has(name)) {
+                writeDraftDebounced("immediate");
+                triggerRerender();
+            }
+            else {
+                writeDraftDebounced();
+                evaluateConditionals();
+            }
+        }
+    }, [mode, writeDraftDebounced]);
+    const setValues = (0, react_1.useCallback)((values, options, skipWriteDraft = false) => {
+        // Flatten incoming values for consistent key access
+        const flattened = (0, utils_2.flattenFormValues)(values);
+        formValues.current = {
+            ...((options === null || options === void 0 ? void 0 : options.overwrite) ? {} : formValues.current),
+            ...flattened,
+        };
+        channelBus.channel("value:*").emit(getValues());
+        // 🔔 Notify all affected subscribers
+        Object.keys(flattened).forEach((key) => {
+            channelBus.channel(`value:${key}`).emit(getValue(key));
+            notifySubscribers(key);
+        });
+        if (!skipWriteDraft) {
+            // Trigger rerender when structure changes
+            triggerRerender();
+            writeDraftDebounced();
+        }
+    }, [writeDraftDebounced, triggerRerender]);
+    const getValue = (0, react_1.useCallback)((name) => (0, deep_path_1.getValueByPath)(getValues(), name), []);
+    const getValues = (0, react_1.useCallback)(() => (0, utils_2.nestFormValues)(formValues.current), []);
+    const setFieldError = (0, react_1.useCallback)((name, error) => {
+        var _a;
+        const prevError = formErrors.current[name];
+        // Prevent triggering the same error again
+        if (prevError === error)
+            return;
+        formErrors.current[name] = errorParser ? errorParser(error !== null && error !== void 0 ? error : "") : error;
+        // notify only the affected field
+        (_a = fieldErrorSubscribersRef.current[name]) === null || _a === void 0 ? void 0 : _a.forEach((fn) => fn(error));
+    }, []);
+    const setErrors = (0, react_1.useCallback)((errors) => {
+        if (!errors || Object.keys(errors).length === 0)
+            return Object.keys(fieldErrorSubscribersRef.current).forEach((key) => {
+                setFieldError(key, undefined);
+            });
+        const mapped = (0, zod_helpers_1.isZodError)(errors) ? (0, zod_helpers_1.mapZodErrors)(errors) : errors;
+        Object.keys(formErrors.current).forEach((key) => {
+            setFieldError(key, undefined);
+        });
+        Object.keys(mapped).forEach((key) => {
+            setFieldError(key, mapped[key]);
+        });
+    }, [setFieldError]);
+    const getError = (0, react_1.useCallback)((name) => (0, deep_path_1.getValueByPath)(formErrors.current, name), []);
+    const getErrors = (0, react_1.useCallback)(() => formErrors.current, []);
+    function resetErrors() {
+        if (!formErrors.current || Object.keys(formErrors.current).length === 0)
+            return;
+        setErrors(Object.keys(formErrors.current).reduce((acc, key) => {
+            acc[key] = undefined;
+            return acc;
+        }, {}));
+    }
+    //validate single field
+    const validateField = (0, react_1.useCallback)((0, utils_1.debounce)(async (name, inputValue) => {
+        var _a;
+        if (!name || !currentSchema.current || mode === "uncontrolled")
+            return;
+        const result = await (0, utils_1.validateForm)(currentSchema.current, {
+            [name]: inputValue,
+        });
+        if (!result.success) {
+            const fieldError = (_a = result.errors[name]) !== null && _a !== void 0 ? _a : undefined;
+            setFieldError(name, fieldError);
+        }
+        else {
+            setFieldError(name, undefined);
+        }
+    }, 150), [currentSchema, mode, setFieldError]);
+    async function formValidation() {
+        if (!currentSchema.current || mode === "uncontrolled")
+            return { isValidated: false, formValues: formValues.current };
+        const result = await (0, utils_1.validateForm)(currentSchema.current, formValues.current);
+        if (result.success) {
+            formValues.current = (0, utils_2.flattenFormValues)(result.data);
+        }
+        return {
+            isValidated: result.success,
+            formValues: result.data,
+            formErrors: !result.success ? result.errors : undefined,
+        };
+    }
+    const validatePartial = (0, react_1.useCallback)(async (values) => {
+        if (!currentSchema.current || mode === "uncontrolled")
+            return;
+        const flat = (0, utils_2.flattenFormValues)(values);
+        const fields = {};
+        for (const [key, val] of Object.entries(flat)) {
+            //@ts-ignore
+            fields[key] = val;
+        }
+        const result = await (0, utils_1.validateForm)(currentSchema.current, fields);
+        if (!result.success) {
+            const errors = {};
+            for (const [key, _] of Object.entries(flat)) {
+                //@ts-ignore
+                errors[key] = result.errors[key];
+            }
+            setErrors({ ...formErrors.current, ...errors });
+        }
+    }, []);
+    //run validation before submit
+    async function validateAndSubmit() {
+        // resetErrors();
+        // 1️⃣ Schema validation
+        if (currentSchema.current &&
+            (validateOn === "change-submit" || validateOn === "submit")) {
+            const validate = await formValidation();
+            if (!validate.isValidated) {
+                setIsValidated(false);
+                setErrors(validate.formErrors);
+                focusFirst(validate.formErrors);
+                return;
+            }
+            resetErrors();
+        }
+        // 2️⃣ Custom check
+        if (check) {
+            //@ts-ignore
+            const checkResult = await check(getValues(), {
+                multiPathError: utils_2.multiPathError,
+                focus,
+                // setErrors,
+                // mapErrors: (errors, path) => setErrors(mapErrors(errors, path)),
+            });
+            if (checkResult && Object.keys(checkResult).length > 0) {
+                setIsValidated(false);
+                setErrors(checkResult);
+                focusFirst(checkResult);
+                return;
+            }
+            resetErrors();
+        }
+        // resetErrors();
+        return getValues();
+    }
+    const register = (0, react_1.useCallback)((name, options, internal) => {
+        const [error, setError] = (0, react_1.useState)(formErrors.current[name]);
+        // internal value ref
+        const valueRef = (0, react_1.useRef)(getValue(name));
+        const refId = name + "-" + (0, react_1.useId)();
+        // setup field metadata on mount
+        (0, react_1.useEffect)(() => {
+            if (options) {
+                fieldRegistryRef.current[name] = options;
+                if (options.transform) {
+                    const arr = Array.isArray(options.transform)
+                        ? options.transform
+                        : [options.transform];
+                    fieldsTransformsRef.current.set(name, arr);
+                }
+                else {
+                    fieldsTransformsRef.current.delete(name);
+                }
+                //@ts-ignore
+                if (options.compute) {
+                    //@ts-ignore
+                    const { deps, fn } = options.compute;
+                    compute(name, deps, fn);
+                }
+                if (options.validate) {
+                    fieldsValidationsRef.current.set(name, options.validate);
+                }
+                else {
+                    fieldsValidationsRef.current.delete(name);
+                }
+                // handle defaultValue only when field is initially undefined
+                const currentValue = getValue(name);
+                if (options.defaultValue !== undefined &&
+                    currentValue === undefined) {
+                    setValue(name, options.defaultValue, { silent: true });
+                }
+            }
+            if (!internal) {
+                // subscribe to internal store → updates ref but not UI
+                const unsub = subscribe(name, (val) => {
+                    valueRef.current = val;
+                });
+                const unsubError = subscribeFieldError(name, setError);
+                return () => {
+                    unsub();
+                    unsubError();
+                    delete fieldRegistryRef.current[name];
+                    fieldsTransformsRef.current.delete(name);
+                    fieldsValidationsRef.current.delete(name);
+                };
+            }
+        }, [name, options]); // keep stable
+        // handlers
+        const onChange = (0, react_1.useCallback)((e) => {
+            var _a, _b;
+            const val = (_b = (_a = e === null || e === void 0 ? void 0 : e.target) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : e;
+            setValue(name, val);
+            touchedFieldsRef.current[name] = true;
+            dirtyFieldsRef.current[name] = true;
+            if (["change", "change-submit"].includes(validateOn)) {
+                validateField(name);
+            }
+        }, [name]);
+        const onBlur = (0, react_1.useCallback)(() => {
+            touchedFieldsRef.current[name] = true;
+            if (validateOn === "blur") {
+                validateField(name);
+            }
+        }, [name]);
+        return {
+            name,
+            defaultValue: valueRef.current,
+            onChange,
+            onBlur,
+            "data-input-ref": refId,
+            "data-input-error": !!error,
+            "aria-invalid": !!error,
+        };
+    }, []);
+    const focus = (0, react_1.useCallback)((name) => {
+        if (typeof document === "undefined")
+            return;
+        const ref = fieldRefs.current[name];
+        const element = document.querySelector(`[data-input-ref="${ref}"]`);
+        if (element && typeof element.focus === "function") {
+            element.focus();
+        }
+    }, []);
+    function focusFirst(obj) {
+        if (!obj || !autoFocusOnError)
+            return;
+        const first = Object.keys(obj)[0];
+        focus(first);
+    }
+    // --- Public notify() ---
+    function notifySubscribers(path) {
+        pendingFields.add(path);
+        scheduleNotify();
+    }
+    function scheduleNotify() {
+        if (notifyScheduled)
+            return;
+        notifyScheduled = true;
+        queueMicrotask(() => {
+            notifyScheduled = false;
+            // Capture and clear pending fields
+            const fields = Array.from(pendingFields);
+            pendingFields.clear();
+            // 1️⃣ Notify all relevant field subscribers
+            for (const [subPath, subscribers] of Object.entries(fieldSubscribersRef.current)) {
+                const shouldNotify = fields.some((path) => path === subPath || path.startsWith(`${subPath}.`));
+                if (shouldNotify) {
+                    const value = getValue(subPath) || "";
+                    for (const cb of subscribers) {
+                        cb(value);
+                    }
+                }
+            }
+            // 2️⃣ Notify global subscribers once
+            if (globalSubscribers.current.size > 0) {
+                for (const cb of globalSubscribers.current) {
+                    cb(getValues());
+                }
+            }
+        });
+    }
+    const subscribe = (0, react_1.useCallback)((nameOrCallback, callback, opts) => {
+        // --- GLOBAL SUBSCRIPTION ---
+        if (typeof nameOrCallback === "function") {
+            globalSubscribers.current.add(nameOrCallback);
+            return () => {
+                globalSubscribers.current.delete(nameOrCallback);
+            };
+        }
+        // --- FIELD SUBSCRIPTION ---
+        const fields = Array.isArray(nameOrCallback)
+            ? nameOrCallback
+            : [nameOrCallback];
+        const cb = callback;
+        for (const field of fields) {
+            // Associate ref (for cleanup when unmounting a field)
+            if (opts === null || opts === void 0 ? void 0 : opts.internalRef) {
+                fieldRefs.current[field] = opts.internalRef;
+            }
+            // Create new set if it doesn’t exist
+            let subscribers = fieldSubscribersRef.current[field];
+            if (!subscribers) {
+                subscribers = new Set();
+                fieldSubscribersRef.current[field] = subscribers;
+            }
+            cb(getValue(field));
+            subscribers.add(cb);
+        }
+        // --- UNSUBSCRIBE CLEANUP ---
+        return () => {
+            for (const field of fields) {
+                const subscribers = fieldSubscribersRef.current[field];
+                if (!subscribers)
+                    continue;
+                subscribers.delete(cb);
+                // If no subscribers remain, clean up
+                if (subscribers.size === 0) {
+                    delete fieldSubscribersRef.current[field];
+                    // Optional: clean up fieldRef if linked
+                    if ((opts === null || opts === void 0 ? void 0 : opts.internalRef) &&
+                        fieldRefs.current[field] === opts.internalRef) {
+                        delete fieldRefs.current[field];
+                    }
+                }
+            }
+        };
+    }, []);
+    async function safeCompute(name, fn, index) {
+        if (computing.current.has(name))
+            return; // avoid infinite loops
+        computing.current.add(name);
+        try {
+            //@ts-ignore
+            const result = fn(getValues(), index);
+            const currentValue = getValue(name);
+            if (result instanceof Promise) {
+                result.then((value) => {
+                    if (value !== currentValue) {
+                        setValue(name, value);
+                    }
+                });
+            }
+            else {
+                if (result !== currentValue) {
+                    setValue(name, result);
+                }
+            }
+        }
+        finally {
+            computing.current.delete(name);
+        }
+    }
+    const compute = (0, react_1.useCallback)((name, depsOrFn, maybeFn, index) => {
+        const deps = Array.isArray(depsOrFn) ? depsOrFn : null;
+        const fn = Array.isArray(depsOrFn) ? maybeFn : depsOrFn;
+        if (deps && deps.includes(name))
+            throw new Error(`Computed field "${name}" cannot depend on itself.`);
+        // if (Object.keys(formValues.current || {}).includes(name)) {
+        //   throw new Error(`Computed field "${name}" already exists`);
+        // }
+        if (typeof fn !== "function") {
+            throw new Error("Invalid compute function");
+        }
+        // Store for introspection
+        //@ts-ignore
+        computedFieldsRef.current[name] = { deps, fn };
+        // Initial compute
+        void safeCompute(name, fn, index);
+        // Subscribe to form changes
+        if (deps && deps.length > 0) {
+            deps.forEach((dep) => {
+                subscribe(dep, () => void safeCompute(name, fn, index));
+            });
+        }
+        else {
+            subscribe(() => void safeCompute(name, fn, index));
+        }
+    }, []);
+    const transform = (0, react_1.useCallback)((path, fn) => {
+        if (!fieldsTransformsRef.current.has(path)) {
+            fieldsTransformsRef.current.set(path, []);
+        }
+        fieldsTransformsRef.current.get(path).push(fn);
+        //@ts-ignore
+        setValue(path, fn(getValue(path)));
+    }, []);
+    function applyTransformations(path, value) {
+        const fns = fieldsTransformsRef.current.get(path);
+        if (fns) {
+            for (const transformFn of fns) {
+                value = transformFn(value);
+            }
+        }
+        return value;
+    }
+    function evaluateConditionals() {
+        var _a, _b;
+        const values = getValues();
+        // reset ephemeral metadata (we re-evaluate everything)
+        hiddenFieldsRef.current = { ...(hiddenFieldsRef.current || {}) };
+        requiredFieldsRef.current = { ...(requiredFieldsRef.current || {}) };
+        unregisteredRef.current = { ...(unregisteredRef.current || {}) };
+        for (const rule of conditionalRulesRef.current) {
+            const { fields, config } = rule;
+            let result;
+            try {
+                result = Boolean(config.when(values));
+            }
+            catch (err) {
+                // if the condition throws, treat as false and continue
+                result = false;
+                // optionally log or surface dev warning
+                // console.warn("conditional when() threw for rule", rule, err);
+            }
+            const effects = result ? (_a = config.then) !== null && _a !== void 0 ? _a : {} : (_b = config.else) !== null && _b !== void 0 ? _b : {};
+            for (const field of fields) {
+                // apply visibility
+                if (effects.visible !== undefined) {
+                    hiddenFieldsRef.current[field] = !effects.visible;
+                }
+                // apply unregister or clear behavior when hidden
+                const isHidden = hiddenFieldsRef.current[field] === true;
+                if (isHidden) {
+                    if (effects.clear) {
+                        // clear the value silently (avoid firing user-level subscriptions twice)
+                        setValue(field, undefined, { silent: true });
+                    }
+                    if (effects.unregister) {
+                        unregisteredRef.current[field] = true;
+                        // form.unregister(field);
+                    }
+                    // remove errors for hidden field
+                    delete formErrors.current[field];
+                }
+                else {
+                    // field visible → ensure unregister flag false
+                    unregisteredRef.current[field] = false;
+                }
+            }
+        }
+        notifyConditionalChange();
+    }
+    const conditional = (0, react_1.useCallback)((fields, cfg) => {
+        const normalized = Array.isArray(fields) ? fields : [fields];
+        conditionalRulesRef.current.push({
+            fields: normalized,
+            config: cfg,
+        });
+        // evaluate immediately so state is correct before UI renders
+        evaluateConditionals();
+        // return an unregister handle for this rule.
+        const ruleIndex = conditionalRulesRef.current.length - 1;
+        return () => {
+            conditionalRulesRef.current.splice(ruleIndex, 1);
+            evaluateConditionals();
+        };
+    }, []);
+    function subscribeVisibility(name, cb) {
+        if (!visibilitySubscribersRef.current[name]) {
+            visibilitySubscribersRef.current[name] = new Set();
+        }
+        visibilitySubscribersRef.current[name].add(cb);
+        return () => {
+            visibilitySubscribersRef.current[name].delete(cb);
+            if (visibilitySubscribersRef.current[name].size === 0) {
+                delete visibilitySubscribersRef.current[name];
+            }
+        };
+    }
+    function notifyConditionalChange() {
+        const map = visibilitySubscribersRef.current;
+        for (const key in map) {
+            const set = map[key];
+            set.forEach((cb) => cb());
+        }
+    }
+    const watch = (0, react_1.useCallback)((fields) => {
+        // If no fields provided, watch all fields
+        const fieldsToWatch = !fields
+            ? Object.keys(formValues.current) // Watch all fields
+            : Array.isArray(fields)
+                ? fields
+                : [fields];
+        if (!fields)
+            watchedFieldsRef.current.clear();
+        // Track fields for reactivity
+        fieldsToWatch.forEach((field) => {
+            if (field) {
+                // Ensure field is not empty
+                watchedFieldsRef.current.add(field);
+            }
+        });
+        // Return current values
+        if (!fields)
+            return getValues();
+        const result = fieldsToWatch.map((field) => getValue(field));
+        if (!Array.isArray(fields) && result.length === 1)
+            return result[0];
+        if (Array.isArray(fields)) {
+            // Return both array and object types
+            return Object.assign(result, Object.fromEntries(fields.map((field, index) => [field, result[index]])));
+        }
+        return result;
+    }, []);
+    const subscribeFieldError = (0, react_1.useCallback)((name, callback) => {
+        if (!fieldErrorSubscribersRef.current[name]) {
+            fieldErrorSubscribersRef.current[name] = new Set();
+        }
+        const set = fieldErrorSubscribersRef.current[name];
+        set.add(callback);
+        // immediately emit current error
+        callback(formErrors.current[name]);
+        return () => {
+            set.delete(callback);
+            if (set.size === 0) {
+                delete fieldErrorSubscribersRef.current[name];
+            }
+        };
+    }, []);
+    const unsubscribeField = (0, react_1.useCallback)((name, callback) => {
+        const set = fieldSubscribersRef.current[name];
+        if (set && callback)
+            set.delete(callback);
+        delete fieldErrorSubscribersRef.current[name];
+        delete fieldRefs.current[name];
+        delete dirtyFieldsRef.current[name];
+        delete touchedFieldsRef.current[name];
+        delete computedFieldsRef.current[name];
+        fieldsTransformsRef.current.delete(name);
+        delete formErrors.current[name];
+        fieldsValidationsRef.current.delete(name);
+    }, []);
+    const unsubscribeFieldPrefix = (0, react_1.useCallback)((prefix) => {
+        for (const key of Object.keys(fieldSubscribersRef.current)) {
+            if (key.startsWith(prefix)) {
+                fieldSubscribersRef.current[key].forEach((cb) => {
+                    unsubscribeField(key, cb);
+                });
+            }
+        }
+    }, [unsubscribeField]);
+    const reset = (0, react_1.useCallback)(() => {
+        Object.keys(fieldSubscribersRef.current).forEach((name) => { var _a; return (_a = fieldSubscribersRef.current[name]) === null || _a === void 0 ? void 0 : _a.forEach((cb) => cb("")); });
+        Object.keys(fieldErrorSubscribersRef.current).forEach((name) => { var _a; return (_a = fieldErrorSubscribersRef.current[name]) === null || _a === void 0 ? void 0 : _a.forEach((fn) => fn(undefined)); });
+        dirtyFieldsRef.current = {};
+        setValues({ ...generatePlaceholders, ...defaultValues }, { overwrite: true }, true);
+        channelBus.channel("value:*").emit({});
+        setErrors({});
+        if (persistKey)
+            (0, utils_1.deleteDraft)(persistKey);
+        triggerRerender();
+    }, []);
+    const resetField = (0, react_1.useCallback)((name) => {
+        const combined = { ...generatePlaceholders, ...defaultValues };
+        setValue(name, combined[name]);
+        markTouched(name);
+    }, []);
+    const isDirty = (0, react_1.useCallback)((name) => {
+        if (!name)
+            return Object.values(dirtyFieldsRef.current).some(Boolean);
+        return !!dirtyFieldsRef.current[name];
+    }, []);
+    const isTouched = (0, react_1.useCallback)((name) => {
+        if (!name)
+            return Object.values(touchedFieldsRef.current).some(Boolean);
+        return !!touchedFieldsRef.current[name];
+    }, []);
+    const markTouched = (0, react_1.useCallback)((name) => {
+        touchedFieldsRef.current[name] = true;
+    }, []);
+    const markDirty = (0, react_1.useCallback)((name) => {
+        dirtyFieldsRef.current[name] = true;
+    }, []);
+    const handleSubmit = (0, react_1.useCallback)((onValid) => {
+        return async (event) => {
+            if (event)
+                event.preventDefault();
+            try {
+                const validatedData = await validateAndSubmit();
+                if (!validatedData)
+                    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),
+                });
+            }
+            finally {
+                setIsSubmitting(false);
+            }
+        };
+    }, []);
+    const field = (0, react_1.useCallback)((path) => {
+        return {
+            get: () => getValue(path),
+            set: (value) => setValue(path, value),
+            transform(fn) {
+                transform(path, fn);
+            },
+            validate: () => {
+                //@ts-ignore
+                validateField(path, getValue(path));
+                //@ts-ignore
+                if (getError(path)) {
+                    focus(path);
+                }
+            },
+            get error() {
+                //@ts-ignore
+                return getError(path);
+            },
+            get hasError() {
+                //@ts-ignore
+                return !!getError(path);
+            },
+            get isTouched() {
+                return isTouched(path);
+            },
+            get isDirty() {
+                return isDirty(path);
+            },
+            focus: () => focus(path),
+            //@ts-ignore
+            reset: () => resetField(path),
+        };
+    }, []);
+    const array = (0, react_1.useCallback)((path) => {
+        return (0, array_helpers_1.formArrayHelper)({
+            path,
+            get formValues() {
+                return formValues.current;
+            },
+            setValues,
+            //@ts-ignore
+            computed,
+            compute,
+            getCurrentArrayValue: () => (0, deep_path_1.getDeepValue)(formValues.current, path),
+        });
+    }, []);
+    const group = (0, react_1.useCallback)((path) => {
+        return (0, group_helpers_1.groupHelpers)({
+            path,
+            //@ts-ignore
+            formValues: formValues.current,
+            //@ts-ignore
+            defaultValues,
+            setValues,
+            getCurrentValue: () => (0, deep_path_1.getDeepValue)(formValues.current, path),
+            validateField,
+            validatePartial,
+        });
+    }, []);
+    const debug = (0, react_1.useCallback)(() => {
+        return {
+            values: { ...getValues() },
+            errors: { ...getErrors() },
+            dirty: { ...(0, utils_2.nestFormValues)(dirtyFieldsRef.current) },
+            touched: { ...(0, utils_2.nestFormValues)(touchedFieldsRef.current) },
+            computed: { ...computedFieldsRef.current },
+            subscriptions: {
+                fields: { ...fieldSubscribersRef.current },
+                errors: { ...fieldErrorSubscribersRef.current },
+            },
+            state: {
+                isSubmitting,
+                isValidated,
+            },
+        };
+    }, []);
+    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 values = {
+        register,
+        validate: async () => {
+            const result = await formValidation();
+            focusFirst(result.formErrors);
+            setErrors(result.formErrors);
+            setIsValidated(result.isValidated);
+        },
+        validateOn,
+        validatePartial,
+        setSchema,
+        setValue,
+        getValue,
+        getValues,
+        setValues,
+        setErrors,
+        getError,
+        getErrors,
+        reset,
+        resetField,
+        handleSubmit,
+        onSubmit: onSubmit ? handleSubmit(onSubmit) : undefined,
+        subscribe,
+        unsubscribeField,
+        subscribeFieldError,
+        errorParser,
+        field,
+        array,
+        group,
+        get values() {
+            return getValues();
+        },
+        get errors() {
+            return getErrors();
+        },
+        isSubmitting,
+        isValidated,
+        isDirty,
+        markDirty,
+        isTouched,
+        markTouched,
+        focus,
+        compute,
+        transform,
+        conditional,
+        onDraftSave,
+        onDraftRestore,
+        debug,
+        watch,
+        Field: components_1.Field,
+        channel: channelBus.channel,
+        meta: formMetadata,
+    };
+    //@ts-ignore
+    if (id)
+        form_registry_1.registry.add(id, values); // synchronous
+    (0, react_1.useEffect)(() => {
+        return () => {
+            if (id)
+                form_registry_1.registry.delete(id);
+        };
+    }, [id]);
+    //@ts-ignore
+    return values;
+}