rn-inputforge 0.4.0 → 0.5.0

package/src/hooks/useFieldFlowForm.ts

@@ -1,6 +1,17 @@
 import { useCallback, useMemo, useRef, useState } from 'react';
+import type { TextInput } from 'react-native';
 import type { FieldFlowRules, ValidationResult } from '../types';
 import { runRules } from '../validation/validators';
+import {
+  getValidationMessages,
+  type FieldFlowLocale,
+  type FieldFlowValidationMessages,
+} from '../i18n/messages';
+import {
+  useFormIntelligence,
+  type UseFormIntelligenceResult,
+} from './useFormIntelligence';
+import type { FormIntelligenceOptions } from '../intelligence/types';
 
 export type FieldFlowFormRules<T extends Record<string, string>> = {
   [K in keyof T]?: FieldFlowRules;
@@ -23,6 +34,27 @@ export interface CrossFieldRule<T extends Record<string, string>> {
   validate: (values: T) => ValidationResult;
 }
 
+export type FieldConditionFn<T extends Record<string, string>> = (values: T) => boolean;
+
+export interface FieldConditionConfig<T extends Record<string, string>> {
+  /** Hide the field when false. Hidden fields are skipped during validation. */
+  showWhen?: FieldConditionFn<T>;
+  /** Dynamically require the field. */
+  requiredWhen?: FieldConditionFn<T>;
+  /** Dynamically disable the field (caller should pass `disabled` to the input). */
+  disabledWhen?: FieldConditionFn<T>;
+}
+
+export type FieldConditions<T extends Record<string, string>> = {
+  [K in keyof T]?: FieldConditionConfig<T>;
+};
+
+export interface FieldVisibilityState {
+  visible: boolean;
+  required: boolean;
+  disabled: boolean;
+}
+
 export interface UseFieldFlowFormOptions<T extends Record<string, string>> {
   initialValues: T;
   rules?: FieldFlowFormRules<T>;
@@ -39,6 +71,10 @@ export interface UseFieldFlowFormOptions<T extends Record<string, string>> {
    * }]
    */
   crossFieldRules?: CrossFieldRule<T>[];
+  /**
+   * Conditional visibility / required / disabled rules evaluated against live values.
+   */
+  conditions?: FieldConditions<T>;
   /**
    * Whole-form validator (e.g. from `zodFormValidate(schema)`).
    * Merged after sync + cross-field rules; field keys map to error messages.
@@ -53,6 +89,20 @@ export interface UseFieldFlowFormOptions<T extends Record<string, string>> {
   asyncValidators?: AsyncFieldValidators<T>;
   /** Debounce for async field validators on change. Default: 400ms. */
   asyncDebounceMs?: number;
+  /**
+   * Enable form intelligence (friction analytics + a11y autofocus/announce on failed submit).
+   * Pass `true` for defaults, or an options object.
+   */
+  intelligence?: boolean | FormIntelligenceOptions;
+  /** Preferred field order for focus-first-error / announcements. */
+  fieldOrder?: (keyof T)[];
+  /**
+   * Locale for default validation messages (`en` | `es` | `fr` | `de` | `pt` | `ar`).
+   * Ignored for rule keys that already pass a custom string message.
+   */
+  locale?: FieldFlowLocale;
+  /** Full message catalog override (wins over `locale`). */
+  messages?: FieldFlowValidationMessages;
   /** Called only when every field passes sync + cross-field + form + async validation. */
   onSubmit?: (values: T) => void | Promise<void>;
 }
@@ -67,30 +117,77 @@ export interface UseFieldFlowFormResult<T extends Record<string, string>> {
   isValid: boolean;
   /** True while any async field validator is in flight. */
   isValidating: boolean;
+  /** True when current values differ from `initialValues`. */
+  isDirty: boolean;
+  /** Per-field dirty flags. */
+  dirtyFields: Partial<Record<keyof T, boolean>>;
   setValue: (field: keyof T, value: string) => void;
+  setValues: (values: T | ((prev: T) => T)) => void;
+  /** Merge server / API errors (e.g. 422 field map). Touches those fields. */
+  setErrors: (errors: Partial<Record<keyof T, string | undefined>>) => void;
+  /** Set a single field error from the server. */
+  setFieldError: (field: keyof T, message: string | undefined) => void;
+  /** Clear one field or all errors. */
+  clearErrors: (field?: keyof T) => void;
   handleChange: (field: keyof T) => (value: string) => void;
   handleBlur: (field: keyof T) => () => void;
+  handleFocus: (field: keyof T) => () => void;
   validateField: (field: keyof T) => Promise<boolean>;
+  /** Validate a subset of fields (wizard steps). */
+  validateFields: (fields: (keyof T)[]) => Promise<boolean>;
   validateAll: () => Promise<boolean>;
   submit: () => Promise<void>;
   reset: () => void;
+  /** Evaluate conditional rules for a field against current values. */
+  getFieldState: (field: keyof T) => FieldVisibilityState;
+  isVisible: (field: keyof T) => boolean;
+  isRequired: (field: keyof T) => boolean;
+  isDisabled: (field: keyof T) => boolean;
+  /**
+   * Convenience props to spread onto a FieldFlow input for a given field.
+   * Respects visibility (returns `null` when hidden so you can short-circuit render).
+   */
+  getInputProps: (
+    field: keyof T,
+  ) => null | {
+    value: string;
+    onChangeText: (value: string) => void;
+    onBlur: () => void;
+    onFocus: () => void;
+    errorText: string | undefined;
+    required: boolean;
+    disabled: boolean;
+  };
+  /** Present when `intelligence` is enabled. */
+  intelligence: UseFormIntelligenceResult<Extract<keyof T, string>> | null;
+  /** Register a TextInput ref for a11y autofocus (intelligence). */
+  registerFieldRef: (
+    field: keyof T,
+    ref: { current: TextInput | null } | TextInput | null,
+  ) => void;
 }
 
 /**
  * Drop-in form state manager for a set of FieldFlow inputs. Handles values,
- * per-field + cross-field + async validation, touched-state, and submission.
+ * per-field + cross-field + conditional + async validation, touched-state,
+ * optional form intelligence, and submission.
  */
 export function useFieldFlowForm<T extends Record<string, string>>({
   initialValues,
   rules,
   crossFieldRules,
+  conditions,
   formValidate,
   asyncValidators,
   asyncDebounceMs = 400,
+  intelligence: intelligenceOpt,
+  fieldOrder,
+  locale = 'en',
+  messages: messagesOverride,
   onSubmit,
 }: UseFieldFlowFormOptions<T>): UseFieldFlowFormResult<T> {
-  const [values, setValues] = useState<T>(initialValues);
-  const [errors, setErrors] = useState<Partial<Record<keyof T, string>>>({});
+  const [values, setValuesState] = useState<T>(initialValues);
+  const [errors, setErrorsState] = useState<Partial<Record<keyof T, string>>>({});
   const [touched, setTouched] = useState<Partial<Record<keyof T, boolean>>>({});
   const [validating, setValidating] = useState<Partial<Record<keyof T, boolean>>>({});
   const [isSubmitting, setIsSubmitting] = useState(false);
@@ -99,26 +196,76 @@ export function useFieldFlowForm<T extends Record<string, string>>({
   valuesRef.current = values;
   const debounceTimers = useRef<Partial<Record<keyof T, ReturnType<typeof setTimeout>>>>({});
   const asyncGen = useRef(0);
+  const messages = messagesOverride ?? getValidationMessages(locale);
+
+  const intelligenceEnabled = Boolean(intelligenceOpt);
+  const intelligenceOptions: FormIntelligenceOptions =
+    typeof intelligenceOpt === 'object' && intelligenceOpt ? intelligenceOpt : {};
+  const intelligence = useFormIntelligence<Extract<keyof T, string>>(
+    intelligenceEnabled ? intelligenceOptions : { focusFirstError: false, announceErrors: false },
+  );
+
+  const evalFieldState = useCallback(
+    (field: keyof T, allValues: T): FieldVisibilityState => {
+      const cfg = conditions?.[field];
+      const visible = cfg?.showWhen ? cfg.showWhen(allValues) : true;
+      const required = cfg?.requiredWhen ? cfg.requiredWhen(allValues) : Boolean(rules?.[field]?.required);
+      const disabled = cfg?.disabledWhen ? cfg.disabledWhen(allValues) : false;
+      return { visible, required, disabled };
+    },
+    [conditions, rules],
+  );
+
+  const getFieldState = useCallback(
+    (field: keyof T) => evalFieldState(field, valuesRef.current),
+    [evalFieldState],
+  );
+
+  const isVisible = useCallback((field: keyof T) => getFieldState(field).visible, [getFieldState]);
+  const isRequired = useCallback((field: keyof T) => getFieldState(field).required, [getFieldState]);
+  const isDisabled = useCallback((field: keyof T) => getFieldState(field).disabled, [getFieldState]);
+
+  const effectiveRulesFor = useCallback(
+    (field: keyof T, allValues: T): FieldFlowRules | undefined => {
+      const base = { ...(rules?.[field] ?? {}) };
+      const state = evalFieldState(field, allValues);
+      if (state.required && !base.required) {
+        base.required = true;
+      }
+      if (!state.required && base.required && conditions?.[field]?.requiredWhen) {
+        // Dynamically optional — strip required when condition is false
+        delete base.required;
+      }
+      return Object.keys(base).length ? base : undefined;
+    },
+    [rules, evalFieldState, conditions],
+  );
 
   const syncErrorFor = useCallback(
     (field: keyof T, fieldValue: string, allValues: T): string | undefined => {
-      const result = runRules(fieldValue, rules?.[field]);
+      const state = evalFieldState(field, allValues);
+      if (!state.visible) return undefined;
+
+      const result = runRules(fieldValue, effectiveRulesFor(field, allValues), messages);
       if (!result.valid) return result.message;
 
       if (crossFieldRules) {
         for (const rule of crossFieldRules) {
           if (rule.target !== field) continue;
+          const targetVisible = evalFieldState(rule.target, allValues).visible;
+          if (!targetVisible) continue;
           const cross = rule.validate(allValues);
-          if (!cross.valid) return cross.message ?? 'Invalid';
+          if (!cross.valid) return cross.message ?? messages.invalid;
         }
       }
       return undefined;
     },
-    [rules, crossFieldRules],
+    [crossFieldRules, effectiveRulesFor, evalFieldState, messages],
   );
 
   const runAsyncForField = useCallback(
     async (field: keyof T, fieldValue: string, allValues: T): Promise<string | undefined> => {
+      if (!evalFieldState(field, allValues).visible) return undefined;
       const validator = asyncValidators?.[field];
       if (!validator) return undefined;
       setValidating(prev => ({ ...prev, [field]: true }));
@@ -129,7 +276,7 @@ export function useFieldFlowForm<T extends Record<string, string>>({
         setValidating(prev => ({ ...prev, [field]: false }));
       }
     },
-    [asyncValidators],
+    [asyncValidators, evalFieldState],
   );
 
   const scheduleAsync = useCallback(
@@ -142,7 +289,7 @@ export function useFieldFlowForm<T extends Record<string, string>>({
         const gen = ++asyncGen.current;
         const message = await runAsyncForField(field, fieldValue, allValues);
         if (gen !== asyncGen.current) return;
-        setErrors(prev => {
+        setErrorsState(prev => {
           const syncMsg = syncErrorFor(field, fieldValue, allValues);
           if (syncMsg) return { ...prev, [field]: syncMsg };
           return { ...prev, [field]: message };
@@ -155,17 +302,34 @@ export function useFieldFlowForm<T extends Record<string, string>>({
   const validateField = useCallback(
     async (field: keyof T): Promise<boolean> => {
       const allValues = valuesRef.current;
+      if (!evalFieldState(field, allValues).visible) {
+        setErrorsState(prev => ({ ...prev, [field]: undefined }));
+        return true;
+      }
       const fieldValue = allValues[field] ?? '';
       const syncError = syncErrorFor(field, fieldValue, allValues);
       if (syncError) {
-        setErrors(prev => ({ ...prev, [field]: syncError }));
+        setErrorsState(prev => ({ ...prev, [field]: syncError }));
         return false;
       }
       const asyncError = await runAsyncForField(field, fieldValue, allValues);
-      setErrors(prev => ({ ...prev, [field]: asyncError }));
+      setErrorsState(prev => ({ ...prev, [field]: asyncError }));
       return !asyncError;
     },
-    [runAsyncForField, syncErrorFor],
+    [evalFieldState, runAsyncForField, syncErrorFor],
+  );
+
+  const validateFields = useCallback(
+    async (fields: (keyof T)[]): Promise<boolean> => {
+      const results = await Promise.all(fields.map(f => validateField(f)));
+      setTouched(prev => {
+        const next = { ...prev };
+        for (const f of fields) next[f] = true;
+        return next;
+      });
+      return results.every(Boolean);
+    },
+    [validateField],
   );
 
   const validateAll = useCallback(async (): Promise<boolean> => {
@@ -176,32 +340,37 @@ export function useFieldFlowForm<T extends Record<string, string>>({
       ...(rules ? (Object.keys(rules) as (keyof T)[]) : []),
       ...(crossFieldRules?.map(r => r.target) ?? []),
       ...(asyncValidators ? (Object.keys(asyncValidators) as (keyof T)[]) : []),
+      ...(conditions ? (Object.keys(conditions) as (keyof T)[]) : []),
     ]);
 
     for (const key of keys) {
+      if (!evalFieldState(key, allValues).visible) continue;
       const syncError = syncErrorFor(key, allValues[key] ?? '', allValues);
       if (syncError) nextErrors[key] = syncError;
     }
 
     if (crossFieldRules) {
       for (const rule of crossFieldRules) {
+        if (!evalFieldState(rule.target, allValues).visible) continue;
         if (nextErrors[rule.target]) continue;
         const result = rule.validate(allValues);
-        if (!result.valid) nextErrors[rule.target] = result.message ?? 'Invalid';
+        if (!result.valid) nextErrors[rule.target] = result.message ?? messages.invalid;
       }
     }
 
     if (formValidate) {
       const formErrors = await formValidate(allValues);
       for (const key of Object.keys(formErrors) as (keyof T)[]) {
-        const msg = formErrors[key];
-        if (msg && !nextErrors[key]) nextErrors[key] = msg;
+        if (!evalFieldState(key, allValues).visible) continue;
+        const formMsg = formErrors[key];
+        if (formMsg && !nextErrors[key]) nextErrors[key] = formMsg;
       }
     }
 
     if (asyncValidators) {
       await Promise.all(
         (Object.keys(asyncValidators) as (keyof T)[]).map(async key => {
+          if (!evalFieldState(key, allValues).visible) return;
           if (nextErrors[key]) return;
           const asyncError = await runAsyncForField(key, allValues[key] ?? '', allValues);
           if (asyncError) nextErrors[key] = asyncError;
@@ -209,58 +378,162 @@ export function useFieldFlowForm<T extends Record<string, string>>({
       );
     }
 
-    setErrors(nextErrors);
+    setErrorsState(nextErrors);
+    setTouched(prev => {
+      const next = { ...prev };
+      for (const key of keys) {
+        if (evalFieldState(key, allValues).visible) next[key] = true;
+      }
+      return next;
+    });
+
+    const valid = Object.values(nextErrors).every(e => !e);
+    if (intelligenceEnabled) {
+      intelligence.onValidationResult(
+        valid,
+        nextErrors as Partial<Record<Extract<keyof T, string>, string | undefined>>,
+        fieldOrder as Extract<keyof T, string>[] | undefined,
+      );
+    }
+    return valid;
+  }, [
+    rules,
+    crossFieldRules,
+    formValidate,
+    asyncValidators,
+    conditions,
+    evalFieldState,
+    syncErrorFor,
+    runAsyncForField,
+    intelligenceEnabled,
+    intelligence,
+    fieldOrder,
+    messages,
+  ]);
+
+  const setErrors = useCallback((next: Partial<Record<keyof T, string | undefined>>) => {
+    setErrorsState(prev => {
+      const merged = { ...prev };
+      for (const key of Object.keys(next) as (keyof T)[]) {
+        const msg = next[key];
+        if (msg == null || msg === '') delete merged[key];
+        else merged[key] = msg;
+      }
+      return merged;
+    });
     setTouched(prev => {
+      const merged = { ...prev };
+      for (const key of Object.keys(next) as (keyof T)[]) {
+        if (next[key]) merged[key] = true;
+      }
+      return merged;
+    });
+  }, []);
+
+  const setFieldError = useCallback((field: keyof T, message: string | undefined) => {
+    setErrors({ [field]: message } as Partial<Record<keyof T, string | undefined>>);
+  }, [setErrors]);
+
+  const clearErrors = useCallback((field?: keyof T) => {
+    if (field == null) {
+      setErrorsState({});
+      return;
+    }
+    setErrorsState(prev => {
+      if (!prev[field]) return prev;
       const next = { ...prev };
-      for (const key of keys) next[key] = true;
+      delete next[field];
       return next;
     });
-    return Object.values(nextErrors).every(e => !e);
-  }, [rules, crossFieldRules, formValidate, asyncValidators, syncErrorFor, runAsyncForField]);
+  }, []);
 
   const setValue = useCallback((field: keyof T, value: string) => {
-    setValues(prev => {
+    setValuesState(prev => {
       const next = { ...prev, [field]: value };
       valuesRef.current = next;
       return next;
     });
   }, []);
 
+  const setValues = useCallback((next: T | ((prev: T) => T)) => {
+    setValuesState(prev => {
+      const resolved = typeof next === 'function' ? (next as (p: T) => T)(prev) : next;
+      valuesRef.current = resolved;
+      return resolved;
+    });
+  }, []);
+
   const handleChange = useCallback(
     (field: keyof T) => (value: string) => {
       setValue(field, value);
+      if (intelligenceEnabled) {
+        intelligence.trackChange(field as Extract<keyof T, string>);
+      }
       const allValues = { ...valuesRef.current, [field]: value };
 
       if (touched[field]) {
         const syncError = syncErrorFor(field, value, allValues);
-        setErrors(prev => ({ ...prev, [field]: syncError }));
+        setErrorsState(prev => ({ ...prev, [field]: syncError }));
         if (!syncError) scheduleAsync(field, value, allValues);
       }
 
+      // Clear errors for fields that just became hidden
+      if (conditions) {
+        for (const key of Object.keys(conditions) as (keyof T)[]) {
+          if (!evalFieldState(key, allValues).visible) {
+            setErrorsState(prev => (prev[key] ? { ...prev, [key]: undefined } : prev));
+          }
+        }
+      }
+
       if (crossFieldRules) {
         for (const rule of crossFieldRules) {
           if (rule.target === field) continue;
           if (rule.deps && !rule.deps.includes(field)) continue;
           if (!touched[rule.target] && !touched[field]) continue;
+          if (!evalFieldState(rule.target, allValues).visible) continue;
           const result = rule.validate(allValues);
-          setErrors(prev => ({
+          setErrorsState(prev => ({
             ...prev,
             [rule.target]: result.valid
               ? syncErrorFor(rule.target, allValues[rule.target] ?? '', allValues)
-              : result.message ?? 'Invalid',
+              : result.message ?? messages.invalid,
           }));
         }
       }
     },
-    [setValue, touched, syncErrorFor, scheduleAsync, crossFieldRules],
+    [
+      setValue,
+      touched,
+      syncErrorFor,
+      scheduleAsync,
+      crossFieldRules,
+      conditions,
+      evalFieldState,
+      intelligenceEnabled,
+      intelligence,
+      messages,
+    ],
   );
 
   const handleBlur = useCallback(
     (field: keyof T) => () => {
+      if (intelligenceEnabled) {
+        intelligence.trackBlur(field as Extract<keyof T, string>);
+      }
       setTouched(prev => ({ ...prev, [field]: true }));
       void validateField(field);
     },
-    [validateField],
+    [validateField, intelligenceEnabled, intelligence],
+  );
+
+  const handleFocus = useCallback(
+    (field: keyof T) => () => {
+      if (intelligenceEnabled) {
+        intelligence.trackFocus(field as Extract<keyof T, string>);
+      }
+    },
+    [intelligenceEnabled, intelligence],
   );
 
   const submit = useCallback(async () => {
@@ -269,10 +542,11 @@ export function useFieldFlowForm<T extends Record<string, string>>({
     setIsSubmitting(true);
     try {
       await onSubmit?.(valuesRef.current);
+      if (intelligenceEnabled) intelligence.trackSubmitSuccess();
     } finally {
       setIsSubmitting(false);
     }
-  }, [onSubmit, validateAll]);
+  }, [onSubmit, validateAll, intelligenceEnabled, intelligence]);
 
   const reset = useCallback(() => {
     asyncGen.current += 1;
@@ -280,16 +554,56 @@ export function useFieldFlowForm<T extends Record<string, string>>({
       const t = debounceTimers.current[key];
       if (t) clearTimeout(t);
     }
-    setValues(initialValues);
+    setValuesState(initialValues);
     valuesRef.current = initialValues;
-    setErrors({});
+    setErrorsState({});
     setTouched({});
     setValidating({});
-  }, [initialValues]);
+    if (intelligenceEnabled) intelligence.reset();
+  }, [initialValues, intelligenceEnabled, intelligence]);
+
+  const getInputProps = useCallback(
+    (field: keyof T) => {
+      const state = getFieldState(field);
+      if (!state.visible) return null;
+      return {
+        value: values[field] ?? '',
+        onChangeText: handleChange(field),
+        onBlur: handleBlur(field),
+        onFocus: handleFocus(field),
+        errorText: touched[field] ? errors[field] : undefined,
+        required: state.required,
+        disabled: state.disabled,
+      };
+    },
+    [getFieldState, values, handleChange, handleBlur, handleFocus, touched, errors],
+  );
+
+  const registerFieldRef = useCallback(
+    (field: keyof T, ref: { current: TextInput | null } | TextInput | null) => {
+      if (intelligenceEnabled) {
+        intelligence.registerFieldRef(field as Extract<keyof T, string>, ref);
+      }
+    },
+    [intelligenceEnabled, intelligence],
+  );
 
   const isValid = useMemo(() => Object.values(errors).every(e => !e), [errors]);
   const isValidating = useMemo(() => Object.values(validating).some(Boolean), [validating]);
 
+  const dirtyFields = useMemo(() => {
+    const next: Partial<Record<keyof T, boolean>> = {};
+    for (const key of Object.keys(initialValues) as (keyof T)[]) {
+      if ((values[key] ?? '') !== (initialValues[key] ?? '')) next[key] = true;
+    }
+    for (const key of Object.keys(values) as (keyof T)[]) {
+      if ((values[key] ?? '') !== (initialValues[key] ?? '')) next[key] = true;
+    }
+    return next;
+  }, [values, initialValues]);
+
+  const isDirty = useMemo(() => Object.values(dirtyFields).some(Boolean), [dirtyFields]);
+
   return {
     values,
     errors,
@@ -298,12 +612,27 @@ export function useFieldFlowForm<T extends Record<string, string>>({
     isSubmitting,
     isValid,
     isValidating,
+    isDirty,
+    dirtyFields,
     setValue,
+    setValues,
+    setErrors,
+    setFieldError,
+    clearErrors,
     handleChange,
     handleBlur,
+    handleFocus,
     validateField,
+    validateFields,
     validateAll,
     submit,
     reset,
+    getFieldState,
+    isVisible,
+    isRequired,
+    isDisabled,
+    getInputProps,
+    intelligence: intelligenceEnabled ? intelligence : null,
+    registerFieldRef,
   };
 }