rn-inputforge 0.3.0 → 0.4.0

package/src/components/FieldFlowSwitch/FieldFlowSwitch.tsx

@@ -0,0 +1,172 @@
+import React, { useEffect, useMemo, useRef } from 'react';
+import { Animated, Pressable, StyleSheet, Text, View, ViewStyle, TextStyle } from 'react-native';
+import { useFieldFlowTheme, mergeDeep } from '../../theme/ThemeProvider';
+import { defaultTheme } from '../../theme/defaultTheme';
+import { renderFieldFlowIcon, type FieldFlowIconSource } from '../../icons';
+import type { DeepPartial, FieldFlowTheme } from '../../types';
+
+export interface FieldFlowSwitchProps {
+  value: boolean;
+  onChange: (value: boolean) => void;
+  label?: string;
+  helperText?: string;
+  errorText?: string;
+  disabled?: boolean;
+  required?: boolean;
+  switchPosition?: 'left' | 'right';
+  leftIcon?: FieldFlowIconSource;
+  iconSize?: number;
+  /** Track color when on. */
+  onTrackColor?: string;
+  /** Track color when off. */
+  offTrackColor?: string;
+  thumbColor?: string;
+  trackStyle?: ViewStyle;
+  thumbStyle?: ViewStyle;
+  containerStyle?: ViewStyle;
+  labelStyle?: TextStyle;
+  helperStyle?: TextStyle;
+  errorStyle?: TextStyle;
+  theme?: DeepPartial<FieldFlowTheme>;
+  testID?: string;
+}
+
+export function FieldFlowSwitch({
+  value,
+  onChange,
+  label,
+  helperText,
+  errorText,
+  disabled,
+  required,
+  switchPosition = 'right',
+  leftIcon,
+  iconSize = 18,
+  onTrackColor,
+  offTrackColor,
+  thumbColor = '#FFFFFF',
+  trackStyle,
+  thumbStyle,
+  containerStyle,
+  labelStyle,
+  helperStyle,
+  errorStyle,
+  theme: themeOverride,
+  testID,
+}: FieldFlowSwitchProps) {
+  const contextTheme = useFieldFlowTheme();
+  const theme = useMemo(
+    () => (themeOverride ? mergeDeep(contextTheme ?? defaultTheme, themeOverride) : contextTheme ?? defaultTheme),
+    [contextTheme, themeOverride],
+  );
+  const styles = useMemo(() => createStyles(theme, Boolean(disabled)), [theme, disabled]);
+
+  const anim = useRef(new Animated.Value(value ? 1 : 0)).current;
+  useEffect(() => {
+    Animated.timing(anim, {
+      toValue: value ? 1 : 0,
+      duration: theme.animation.duration,
+      useNativeDriver: false,
+    }).start();
+  }, [anim, theme.animation.duration, value]);
+
+  const trackColor = anim.interpolate({
+    inputRange: [0, 1],
+    outputRange: [offTrackColor ?? theme.colors.border, onTrackColor ?? theme.colors.borderFocused],
+  });
+  const thumbTranslate = anim.interpolate({
+    inputRange: [0, 1],
+    outputRange: [2, 22],
+  });
+
+  const switchNode = (
+    <Animated.View style={[styles.track, { backgroundColor: trackColor }, trackStyle]}>
+      <Animated.View
+        style={[styles.thumb, { backgroundColor: thumbColor, transform: [{ translateX: thumbTranslate }] }, thumbStyle]}
+      />
+    </Animated.View>
+  );
+
+  const labelNode = label ? (
+    <Text style={[styles.label, labelStyle]}>
+      {label}
+      {required ? ' *' : ''}
+    </Text>
+  ) : null;
+
+  return (
+    <View style={[styles.wrapper, containerStyle]} testID={testID}>
+      <Pressable
+        onPress={() => !disabled && onChange(!value)}
+        disabled={disabled}
+        style={styles.row}
+        accessibilityRole="switch"
+        accessibilityState={{ checked: value, disabled: Boolean(disabled) }}
+        accessibilityLabel={label}
+        hitSlop={6}
+      >
+        {leftIcon ? (
+          <View style={styles.leftIcon}>{renderFieldFlowIcon(leftIcon, theme.colors.icon, iconSize)}</View>
+        ) : null}
+        {switchPosition === 'left' ? switchNode : null}
+        {labelNode}
+        {switchPosition === 'right' ? switchNode : null}
+      </Pressable>
+      {errorText ? (
+        <Text style={[styles.errorText, errorStyle, helperStyle]}>{errorText}</Text>
+      ) : helperText ? (
+        <Text style={[styles.helperText, helperStyle]}>{helperText}</Text>
+      ) : null}
+    </View>
+  );
+}
+
+function createStyles(theme: FieldFlowTheme, disabled: boolean) {
+  return StyleSheet.create({
+    wrapper: {
+      marginBottom: theme.spacing.gap * 2,
+      opacity: disabled ? 0.6 : 1,
+    },
+    row: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+      gap: theme.spacing.gap,
+    },
+    leftIcon: {
+      marginRight: 2,
+    },
+    label: {
+      flex: 1,
+      fontSize: theme.typography.fontSize,
+      color: theme.colors.text,
+      fontFamily: theme.typography.fontFamily,
+    },
+    track: {
+      width: 44,
+      height: 26,
+      borderRadius: 13,
+      justifyContent: 'center',
+    },
+    thumb: {
+      width: 20,
+      height: 20,
+      borderRadius: 10,
+      shadowColor: '#000',
+      shadowOpacity: 0.15,
+      shadowRadius: 2,
+      shadowOffset: { width: 0, height: 1 },
+      elevation: 2,
+    },
+    helperText: {
+      marginTop: theme.spacing.gap / 1.5,
+      fontSize: theme.typography.helperFontSize,
+      color: theme.colors.label,
+    },
+    errorText: {
+      marginTop: theme.spacing.gap / 1.5,
+      fontSize: theme.typography.helperFontSize,
+      color: theme.colors.error,
+    },
+  });
+}

package/src/components/FieldFlowSwitch/index.ts

@@ -0,0 +1,2 @@
+export { FieldFlowSwitch } from './FieldFlowSwitch';
+export type { FieldFlowSwitchProps } from './FieldFlowSwitch';

package/src/hooks/index.ts

@@ -6,6 +6,9 @@ export type {
   UseFieldFlowFormOptions,
   UseFieldFlowFormResult,
   FieldFlowFormRules,
+  AsyncFieldValidator,
+  AsyncFieldValidators,
+  CrossFieldRule,
 } from './useFieldFlowForm';
 
 export { useFieldState } from './useFieldState';

package/src/hooks/useFieldFlowForm.ts

@@ -1,15 +1,59 @@
-import { useCallback, useMemo, useState } from 'react';
-import type { FieldFlowRules } from '../types';
+import { useCallback, useMemo, useRef, useState } from 'react';
+import type { FieldFlowRules, ValidationResult } from '../types';
 import { runRules } from '../validation/validators';
 
 export type FieldFlowFormRules<T extends Record<string, string>> = {
   [K in keyof T]?: FieldFlowRules;
 };
 
+export type AsyncFieldValidator<T extends Record<string, string>> = (
+  value: string,
+  values: T,
+) => Promise<ValidationResult> | ValidationResult;
+
+export type AsyncFieldValidators<T extends Record<string, string>> = {
+  [K in keyof T]?: AsyncFieldValidator<T>;
+};
+
+export interface CrossFieldRule<T extends Record<string, string>> {
+  /** Field that receives the error message when validation fails. */
+  target: keyof T;
+  /** When set, this rule re-runs when any of these fields change (in addition to `target`). */
+  deps?: (keyof T)[];
+  validate: (values: T) => ValidationResult;
+}
+
 export interface UseFieldFlowFormOptions<T extends Record<string, string>> {
   initialValues: T;
   rules?: FieldFlowFormRules<T>;
-  /** Called only when every field passes validation. */
+  /**
+   * Cross-field rules (e.g. password confirm). Run after per-field sync rules.
+   *
+   * @example
+   * crossFieldRules: [{
+   *   target: 'confirm',
+   *   deps: ['password'],
+   *   validate: v => v.password === v.confirm
+   *     ? { valid: true }
+   *     : { valid: false, message: 'Passwords must match' },
+   * }]
+   */
+  crossFieldRules?: CrossFieldRule<T>[];
+  /**
+   * Whole-form validator (e.g. from `zodFormValidate(schema)`).
+   * Merged after sync + cross-field rules; field keys map to error messages.
+   */
+  formValidate?: (
+    values: T,
+  ) => Partial<Record<keyof T, string | undefined>> | Promise<Partial<Record<keyof T, string | undefined>>>;
+  /**
+   * Per-field async validators (e.g. "email already taken").
+   * Debounced on change after the field has been touched; always awaited on submit.
+   */
+  asyncValidators?: AsyncFieldValidators<T>;
+  /** Debounce for async field validators on change. Default: 400ms. */
+  asyncDebounceMs?: number;
+  /** Called only when every field passes sync + cross-field + form + async validation. */
   onSubmit?: (values: T) => void | Promise<void>;
 }
 
@@ -17,111 +61,243 @@ export interface UseFieldFlowFormResult<T extends Record<string, string>> {
   values: T;
   errors: Partial<Record<keyof T, string>>;
   touched: Partial<Record<keyof T, boolean>>;
+  /** Fields currently waiting on an async validator. */
+  validating: Partial<Record<keyof T, boolean>>;
   isSubmitting: boolean;
   isValid: boolean;
+  /** True while any async field validator is in flight. */
+  isValidating: boolean;
   setValue: (field: keyof T, value: string) => void;
   handleChange: (field: keyof T) => (value: string) => void;
   handleBlur: (field: keyof T) => () => void;
-  validateField: (field: keyof T) => boolean;
-  validateAll: () => boolean;
+  validateField: (field: keyof T) => Promise<boolean>;
+  validateAll: () => Promise<boolean>;
   submit: () => Promise<void>;
   reset: () => void;
 }
 
 /**
  * Drop-in form state manager for a set of FieldFlow inputs. Handles values,
- * per-field + whole-form validation (via the same `FieldFlowRules` used by
- * the input components), touched-state, and submission.
+ * per-field + cross-field + async validation, touched-state, and submission.
  */
 export function useFieldFlowForm<T extends Record<string, string>>({
   initialValues,
   rules,
+  crossFieldRules,
+  formValidate,
+  asyncValidators,
+  asyncDebounceMs = 400,
   onSubmit,
 }: UseFieldFlowFormOptions<T>): UseFieldFlowFormResult<T> {
   const [values, setValues] = useState<T>(initialValues);
   const [errors, setErrors] = 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);
 
+  const valuesRef = useRef(values);
+  valuesRef.current = values;
+  const debounceTimers = useRef<Partial<Record<keyof T, ReturnType<typeof setTimeout>>>>({});
+  const asyncGen = useRef(0);
+
+  const syncErrorFor = useCallback(
+    (field: keyof T, fieldValue: string, allValues: T): string | undefined => {
+      const result = runRules(fieldValue, rules?.[field]);
+      if (!result.valid) return result.message;
+
+      if (crossFieldRules) {
+        for (const rule of crossFieldRules) {
+          if (rule.target !== field) continue;
+          const cross = rule.validate(allValues);
+          if (!cross.valid) return cross.message ?? 'Invalid';
+        }
+      }
+      return undefined;
+    },
+    [rules, crossFieldRules],
+  );
+
+  const runAsyncForField = useCallback(
+    async (field: keyof T, fieldValue: string, allValues: T): Promise<string | undefined> => {
+      const validator = asyncValidators?.[field];
+      if (!validator) return undefined;
+      setValidating(prev => ({ ...prev, [field]: true }));
+      try {
+        const result = await validator(fieldValue, allValues);
+        return result.valid ? undefined : result.message;
+      } finally {
+        setValidating(prev => ({ ...prev, [field]: false }));
+      }
+    },
+    [asyncValidators],
+  );
+
+  const scheduleAsync = useCallback(
+    (field: keyof T, fieldValue: string, allValues: T) => {
+      if (!asyncValidators?.[field]) return;
+      const existing = debounceTimers.current[field];
+      if (existing) clearTimeout(existing);
+
+      debounceTimers.current[field] = setTimeout(async () => {
+        const gen = ++asyncGen.current;
+        const message = await runAsyncForField(field, fieldValue, allValues);
+        if (gen !== asyncGen.current) return;
+        setErrors(prev => {
+          const syncMsg = syncErrorFor(field, fieldValue, allValues);
+          if (syncMsg) return { ...prev, [field]: syncMsg };
+          return { ...prev, [field]: message };
+        });
+      }, asyncDebounceMs);
+    },
+    [asyncDebounceMs, asyncValidators, runAsyncForField, syncErrorFor],
+  );
+
   const validateField = useCallback(
-    (field: keyof T): boolean => {
-      const fieldRules = rules?.[field];
-      const result = runRules(values[field] ?? '', fieldRules);
-      setErrors(prev => ({ ...prev, [field]: result.valid ? undefined : result.message }));
-      return result.valid;
+    async (field: keyof T): Promise<boolean> => {
+      const allValues = valuesRef.current;
+      const fieldValue = allValues[field] ?? '';
+      const syncError = syncErrorFor(field, fieldValue, allValues);
+      if (syncError) {
+        setErrors(prev => ({ ...prev, [field]: syncError }));
+        return false;
+      }
+      const asyncError = await runAsyncForField(field, fieldValue, allValues);
+      setErrors(prev => ({ ...prev, [field]: asyncError }));
+      return !asyncError;
     },
-    [rules, values],
+    [runAsyncForField, syncErrorFor],
   );
 
-  const validateAll = useCallback((): boolean => {
-    if (!rules) return true;
-    let allValid = true;
+  const validateAll = useCallback(async (): Promise<boolean> => {
+    const allValues = valuesRef.current;
     const nextErrors: Partial<Record<keyof T, string>> = {};
-    for (const key of Object.keys(rules) as (keyof T)[]) {
-      const result = runRules(values[key] ?? '', rules[key]);
-      if (!result.valid) {
-        allValid = false;
-        nextErrors[key] = result.message;
+    const keys = new Set<keyof T>([
+      ...(Object.keys(allValues) as (keyof T)[]),
+      ...(rules ? (Object.keys(rules) as (keyof T)[]) : []),
+      ...(crossFieldRules?.map(r => r.target) ?? []),
+      ...(asyncValidators ? (Object.keys(asyncValidators) as (keyof T)[]) : []),
+    ]);
+
+    for (const key of keys) {
+      const syncError = syncErrorFor(key, allValues[key] ?? '', allValues);
+      if (syncError) nextErrors[key] = syncError;
+    }
+
+    if (crossFieldRules) {
+      for (const rule of crossFieldRules) {
+        if (nextErrors[rule.target]) continue;
+        const result = rule.validate(allValues);
+        if (!result.valid) nextErrors[rule.target] = result.message ?? '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 (asyncValidators) {
+      await Promise.all(
+        (Object.keys(asyncValidators) as (keyof T)[]).map(async key => {
+          if (nextErrors[key]) return;
+          const asyncError = await runAsyncForField(key, allValues[key] ?? '', allValues);
+          if (asyncError) nextErrors[key] = asyncError;
+        }),
+      );
+    }
+
     setErrors(nextErrors);
     setTouched(prev => {
       const next = { ...prev };
-      for (const key of Object.keys(rules)) next[key as keyof T] = true;
+      for (const key of keys) next[key] = true;
       return next;
     });
-    return allValid;
-  }, [rules, values]);
+    return Object.values(nextErrors).every(e => !e);
+  }, [rules, crossFieldRules, formValidate, asyncValidators, syncErrorFor, runAsyncForField]);
 
   const setValue = useCallback((field: keyof T, value: string) => {
-    setValues(prev => ({ ...prev, [field]: value }));
+    setValues(prev => {
+      const next = { ...prev, [field]: value };
+      valuesRef.current = next;
+      return next;
+    });
   }, []);
 
   const handleChange = useCallback(
     (field: keyof T) => (value: string) => {
       setValue(field, value);
+      const allValues = { ...valuesRef.current, [field]: value };
+
       if (touched[field]) {
-        // live-validate once the user has already blurred this field once
-        const result = runRules(value, rules?.[field]);
-        setErrors(prev => ({ ...prev, [field]: result.valid ? undefined : result.message }));
+        const syncError = syncErrorFor(field, value, allValues);
+        setErrors(prev => ({ ...prev, [field]: syncError }));
+        if (!syncError) scheduleAsync(field, value, allValues);
+      }
+
+      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;
+          const result = rule.validate(allValues);
+          setErrors(prev => ({
+            ...prev,
+            [rule.target]: result.valid
+              ? syncErrorFor(rule.target, allValues[rule.target] ?? '', allValues)
+              : result.message ?? 'Invalid',
+          }));
+        }
       }
     },
-    [rules, setValue, touched],
+    [setValue, touched, syncErrorFor, scheduleAsync, crossFieldRules],
   );
 
   const handleBlur = useCallback(
     (field: keyof T) => () => {
       setTouched(prev => ({ ...prev, [field]: true }));
-      validateField(field);
+      void validateField(field);
     },
     [validateField],
   );
 
   const submit = useCallback(async () => {
-    const valid = validateAll();
+    const valid = await validateAll();
     if (!valid) return;
     setIsSubmitting(true);
     try {
-      await onSubmit?.(values);
+      await onSubmit?.(valuesRef.current);
     } finally {
       setIsSubmitting(false);
     }
-  }, [onSubmit, validateAll, values]);
+  }, [onSubmit, validateAll]);
 
   const reset = useCallback(() => {
+    asyncGen.current += 1;
+    for (const key of Object.keys(debounceTimers.current) as (keyof T)[]) {
+      const t = debounceTimers.current[key];
+      if (t) clearTimeout(t);
+    }
     setValues(initialValues);
+    valuesRef.current = initialValues;
     setErrors({});
     setTouched({});
+    setValidating({});
   }, [initialValues]);
 
   const isValid = useMemo(() => Object.values(errors).every(e => !e), [errors]);
+  const isValidating = useMemo(() => Object.values(validating).some(Boolean), [validating]);
 
   return {
     values,
     errors,
     touched,
+    validating,
     isSubmitting,
     isValid,
+    isValidating,
     setValue,
     handleChange,
     handleBlur,