@formality-ui/react 0.2.1 → 0.2.3

package/dist/index.d.cts

@@ -581,7 +581,15 @@ interface FormProps<TFieldValues extends FieldValues = FieldValues> {
     record?: Partial<TFieldValues>;
     /** Enable auto-save on field changes */
     autoSave?: boolean;
-    /** Debounce milliseconds for auto-save. false = immediate submission, number = delay in milliseconds (default: 1000) */
+    /**
+     * Form-level auto-save debounce, used as the fallback for any field whose
+     * `InputConfig.debounce` is unset.
+     * - `false` — submit immediately (no debounce timer).
+     * - `number` — delay auto-save by this many milliseconds (default: 1000).
+     *
+     * A field can override its own cadence via `InputConfig.debounce`
+     * (`false` for immediate, or a number for a per-field delay).
+     */
     debounce?: number | false;
     /** Form-level validation */
     validate?: (values: Partial<TFieldValues>) => Record<string, string> | Promise<Record<string, string>>;

package/dist/index.d.ts

@@ -581,7 +581,15 @@ interface FormProps<TFieldValues extends FieldValues = FieldValues> {
     record?: Partial<TFieldValues>;
     /** Enable auto-save on field changes */
     autoSave?: boolean;
-    /** Debounce milliseconds for auto-save. false = immediate submission, number = delay in milliseconds (default: 1000) */
+    /**
+     * Form-level auto-save debounce, used as the fallback for any field whose
+     * `InputConfig.debounce` is unset.
+     * - `false` — submit immediately (no debounce timer).
+     * - `number` — delay auto-save by this many milliseconds (default: 1000).
+     *
+     * A field can override its own cadence via `InputConfig.debounce`
+     * (`false` for immediate, or a number for a per-field delay).
+     */
     debounce?: number | false;
     /** Form-level validation */
     validate?: (values: Partial<TFieldValues>) => Record<string, string> | Promise<Record<string, string>>;

package/dist/index.js

@@ -179,6 +179,8 @@ function Form({
   const pendingChangedFields = useRef(/* @__PURE__ */ new Set());
   const pendingAffectedFields = useRef(/* @__PURE__ */ new Set());
   const executionVersionRef = useRef(0);
+  const fieldDebouncersRef = useRef(/* @__PURE__ */ new Map());
+  const getOrCreateDebouncedRef = useRef();
   const registerField = useCallback((name) => {
     fieldRegistry.current.add(name);
     setRegisteredFields(new Set(fieldRegistry.current));
@@ -279,8 +281,11 @@ function Form({
         for (const field of affected) {
           pendingAffectedFields.current.add(field);
         }
-        if (inputConfig?.debounce === false) {
+        const fieldDebounce = inputConfig?.debounce;
+        if (fieldDebounce === false) {
           executeAutoSaveRef.current?.();
+        } else if (typeof fieldDebounce === "number") {
+          getOrCreateDebouncedRef.current?.(fieldDebounce)();
         } else {
           debouncedSubmitRef.current?.();
         }
@@ -421,53 +426,60 @@ function Form({
         return;
       }
     }
-    const formState = methods.formState;
-    if (Object.keys(formState.errors).length > 0) {
-      return;
-    }
     const values = methods.getValues();
     await handleSubmit(values);
   }, [methods, handleSubmit, waitForFieldValidation]);
   executeAutoSaveRef.current = executeAutoSave;
+  const getOrCreateDebounced = useCallback((ms) => {
+    const cached = fieldDebouncersRef.current.get(ms);
+    if (cached) return cached;
+    const fn = wrapDebounced(() => {
+      executeAutoSaveRef.current?.();
+    }, ms);
+    fieldDebouncersRef.current.set(ms, fn);
+    return fn;
+  }, []);
+  getOrCreateDebouncedRef.current = getOrCreateDebounced;
   useEffect(() => {
+    return () => {
+      fieldDebouncersRef.current.forEach((fn) => fn.cancel());
+      fieldDebouncersRef.current.clear();
+    };
+  }, [getOrCreateDebounced]);
+  const debouncedSubmit = useMemo(() => {
     if (debounceMs === false) {
-      const immediateFn = Object.assign(
+      return Object.assign(
         () => {
-          executeAutoSave();
+          executeAutoSaveRef.current?.();
         },
         {
           cancel: () => {
           },
           // No-op for immediate function
-          flush: () => executeAutoSave(),
+          flush: () => executeAutoSaveRef.current?.(),
           // Execute immediately on flush
           pending: () => false
           // Never pending when immediate
         }
       );
-      debouncedSubmitRef.current = immediateFn;
-      return () => {
-      };
     }
-    const debouncedFn = debounce(() => {
-      executeAutoSave();
+    return wrapDebounced(() => {
+      executeAutoSaveRef.current?.();
     }, debounceMs);
-    const fn = Object.assign(debouncedFn, {
-      pending: () => false
-      // lodash debounce handles this internally
-    });
-    debouncedSubmitRef.current = fn;
+  }, [debounceMs]);
+  debouncedSubmitRef.current = debouncedSubmit;
+  useEffect(() => {
     return () => {
-      debouncedFn.cancel();
+      debouncedSubmit.cancel();
     };
-  }, [executeAutoSave, debounceMs]);
+  }, [debouncedSubmit]);
   const submitImmediate = useCallback(() => {
-    if (debouncedSubmitRef.current?.flush) {
-      debouncedSubmitRef.current.flush();
-    } else {
-      executeAutoSave();
-    }
-  }, [executeAutoSave]);
+    const anyPending = debouncedSubmitRef.current?.pending() === true || [...fieldDebouncersRef.current.values()].some((fn) => fn.pending());
+    if (!anyPending) return;
+    debouncedSubmitRef.current?.cancel();
+    fieldDebouncersRef.current.forEach((fn) => fn.cancel());
+    executeAutoSaveRef.current?.();
+  }, []);
   const unusedFields = useMemo(() => {
     const allFields = Object.keys(config);
     return allFields.filter((name) => !registeredFields.has(name));
@@ -506,7 +518,7 @@ function Form({
       setFieldValidating,
       getFormState,
       onSubmit,
-      debouncedSubmit: debouncedSubmitRef.current,
+      debouncedSubmit,
       submitImmediate,
       unusedFields,
       methods
@@ -525,6 +537,7 @@ function Form({
       setFieldValidating,
       getFormState,
       onSubmit,
+      debouncedSubmit,
       submitImmediate,
       unusedFields,
       methods
@@ -539,6 +552,30 @@ function Form({
     resolvedTitle
   }) : children }) }) });
 }
+function wrapDebounced(callback, ms) {
+  let isPending = false;
+  const debounced = debounce(() => {
+    isPending = false;
+    callback();
+  }, ms);
+  return Object.assign(
+    () => {
+      isPending = true;
+      debounced();
+    },
+    {
+      cancel: () => {
+        isPending = false;
+        debounced.cancel();
+      },
+      flush: () => {
+        isPending = false;
+        debounced.flush();
+      },
+      pending: () => isPending
+    }
+  );
+}
 function transformValuesForSubmit(values, config, inputs) {
   const result = {};
   for (const [name, value] of Object.entries(values)) {
@@ -986,18 +1023,52 @@ function Field({
       }
     }
   }, [effectiveSetValue.hasCondition, effectiveSetValue.value, name]);
+  const { providerSelectProps, formSelectProps, fieldSelectProps } = usePropsEvaluation({
+    selectProps: fieldConfig.selectProps,
+    formDefaultFieldProps: formConfig.selectDefaultFieldProps,
+    providerDefaultFieldProps: providerConfig.selectDefaultFieldProps,
+    subscribesTo: fieldConfig.subscribesTo,
+    fieldName: name
+  });
   const isDisabled = useMemo(() => {
     if (disabledProp !== void 0) return disabledProp;
     if (fieldConfig.disabled !== void 0) return fieldConfig.disabled;
     if (conditionResult.hasDisabledCondition)
       return conditionResult.disabled ?? false;
     if (groupContext.state.isDisabled) return true;
+    const propsLayers = [
+      fieldSelectProps,
+      // layer 2: field-level selectProps
+      formSelectProps,
+      // layer 5: form-level selectDefaultFieldProps
+      providerSelectProps,
+      // layer 7: provider-level selectDefaultFieldProps
+      inputConfig.props,
+      // layer 4: input config props
+      fieldConfig.props,
+      // layer 3: field config props
+      formConfig.defaultFieldProps,
+      // layer 6: form-level defaultFieldProps
+      providerConfig.defaultFieldProps
+      // layer 8: provider-level defaultFieldProps
+    ];
+    for (const layer of propsLayers) {
+      const layerDisabled = layer?.disabled;
+      if (layerDisabled !== void 0) return Boolean(layerDisabled);
+    }
     return false;
   }, [
     disabledProp,
     fieldConfig.disabled,
+    fieldConfig.props,
     conditionResult,
-    groupContext.state.isDisabled
+    groupContext.state.isDisabled,
+    fieldSelectProps,
+    formSelectProps,
+    providerSelectProps,
+    inputConfig.props,
+    formConfig.defaultFieldProps,
+    providerConfig.defaultFieldProps
   ]);
   const isVisible = useMemo(() => {
     if (hiddenProp !== void 0) return !hiddenProp;
@@ -1012,13 +1083,6 @@ function Field({
     conditionResult,
     groupContext.state.isVisible
   ]);
-  const { providerSelectProps, formSelectProps, fieldSelectProps } = usePropsEvaluation({
-    selectProps: fieldConfig.selectProps,
-    formDefaultFieldProps: formConfig.selectDefaultFieldProps,
-    providerDefaultFieldProps: providerConfig.selectDefaultFieldProps,
-    subscribesTo: fieldConfig.subscribesTo,
-    fieldName: name
-  });
   const label = useMemo(() => {
     return resolveLabel(name, fieldConfig, fieldSelectProps, restProps);
   }, [name, fieldConfig, fieldSelectProps, restProps]);