rn-inputforge 0.3.1 → 0.5.0

package/src/hooks/useFieldFlowSteps.ts

@@ -0,0 +1,130 @@
+import { useCallback, useMemo, useState } from 'react';
+
+export interface FieldFlowStepDefinition<T extends Record<string, string> = Record<string, string>> {
+  /** Stable id for the step. */
+  id: string;
+  title: string;
+  description?: string;
+  /** Fields that must pass validation before advancing (keys of your form values). */
+  fields?: (keyof T)[];
+  /** Optional guard — return false (or a message) to block next. */
+  canLeave?: (values: T) => boolean | string;
+}
+
+export interface UseFieldFlowStepsOptions<T extends Record<string, string>> {
+  steps: FieldFlowStepDefinition<T>[];
+  /** Form values used by `canLeave` and exposed to callers. */
+  values: T;
+  /**
+   * Validate a subset of fields (usually from `useFieldFlowForm`).
+   * Should return true when all listed fields are valid.
+   */
+  validateFields?: (fields: (keyof T)[]) => Promise<boolean>;
+  /** Initial step index. Default: 0. */
+  initialStep?: number;
+  /** Called when the user completes the last step successfully. */
+  onComplete?: () => void | Promise<void>;
+}
+
+export interface UseFieldFlowStepsResult<T extends Record<string, string>> {
+  steps: FieldFlowStepDefinition<T>[];
+  stepIndex: number;
+  step: FieldFlowStepDefinition<T>;
+  isFirst: boolean;
+  isLast: boolean;
+  progress: number;
+  stepError: string | undefined;
+  goTo: (index: number) => void;
+  next: () => Promise<boolean>;
+  back: () => void;
+  reset: () => void;
+}
+
+/**
+ * Multi-step / wizard controller — pairs with `FieldFlowStepper` and `useFieldFlowForm`.
+ */
+export function useFieldFlowSteps<T extends Record<string, string>>({
+  steps,
+  values,
+  validateFields,
+  initialStep = 0,
+  onComplete,
+}: UseFieldFlowStepsOptions<T>): UseFieldFlowStepsResult<T> {
+  const [stepIndex, setStepIndex] = useState(() =>
+    Math.min(Math.max(0, initialStep), Math.max(0, steps.length - 1)),
+  );
+  const [stepError, setStepError] = useState<string | undefined>();
+
+  const step = steps[stepIndex] ?? steps[0];
+  const isFirst = stepIndex <= 0;
+  const isLast = stepIndex >= steps.length - 1;
+  const progress = steps.length <= 1 ? 1 : stepIndex / (steps.length - 1);
+
+  const goTo = useCallback(
+    (index: number) => {
+      if (index < 0 || index >= steps.length) return;
+      setStepError(undefined);
+      setStepIndex(index);
+    },
+    [steps.length],
+  );
+
+  const back = useCallback(() => {
+    if (isFirst) return;
+    setStepError(undefined);
+    setStepIndex(i => i - 1);
+  }, [isFirst]);
+
+  const next = useCallback(async (): Promise<boolean> => {
+    const current = steps[stepIndex];
+    if (!current) return false;
+
+    if (current.fields?.length && validateFields) {
+      const ok = await validateFields(current.fields);
+      if (!ok) {
+        setStepError(undefined);
+        return false;
+      }
+    }
+
+    if (current.canLeave) {
+      const result = current.canLeave(values);
+      if (result !== true) {
+        setStepError(typeof result === 'string' ? result : 'Please complete this step');
+        return false;
+      }
+    }
+
+    setStepError(undefined);
+
+    if (isLast) {
+      await onComplete?.();
+      return true;
+    }
+
+    setStepIndex(i => i + 1);
+    return true;
+  }, [steps, stepIndex, validateFields, values, isLast, onComplete]);
+
+  const reset = useCallback(() => {
+    setStepIndex(Math.min(Math.max(0, initialStep), Math.max(0, steps.length - 1)));
+    setStepError(undefined);
+  }, [initialStep, steps.length]);
+
+  return useMemo(
+    () => ({
+      steps,
+      stepIndex,
+      step,
+      isFirst,
+      isLast,
+      progress,
+      stepError,
+      goTo,
+      next,
+      back,
+      reset,
+    }),
+    [steps, stepIndex, step, isFirst, isLast, progress, stepError, goTo, next, back, reset],
+  );
+}

package/src/hooks/useFormIntelligence.ts

@@ -0,0 +1,207 @@
+import { useCallback, useMemo, useRef } from 'react';
+import type { TextInput } from 'react-native';
+import {
+  announceForAccessibility,
+  buildValidationAnnouncement,
+  focusFirstError,
+  type FieldRefMap,
+} from '../intelligence/formAccessibility';
+import type {
+  FieldFrictionStats,
+  FormHealthReport,
+  FormIntelligenceOptions,
+} from '../intelligence/types';
+
+function emptyStats(): FieldFrictionStats {
+  return {
+    focusCount: 0,
+    totalFocusMs: 0,
+    errorCount: 0,
+    changeCount: 0,
+    blurCount: 0,
+  };
+}
+
+export interface UseFormIntelligenceResult<T extends string = string> {
+  registerFieldRef: (field: T, ref: { current: TextInput | null } | TextInput | null) => void;
+  trackFocus: (field: T) => void;
+  trackBlur: (field: T) => void;
+  trackChange: (field: T) => void;
+  trackError: (field: T) => void;
+  /** Call after validateAll — handles a11y focus/announce + friction accounting. */
+  onValidationResult: (
+    valid: boolean,
+    errors: Partial<Record<T, string | undefined>>,
+    fieldOrder?: T[],
+  ) => void;
+  trackSubmitSuccess: () => void;
+  getReport: () => FormHealthReport;
+  flush: () => FormHealthReport;
+  reset: () => void;
+}
+
+/**
+ * Tracks per-field friction and runs accessibility autopilot on failed validation.
+ * Designed to plug into `useFieldFlowForm({ intelligence: true })` or be used standalone.
+ */
+export function useFormIntelligence<T extends string = string>(
+  options: FormIntelligenceOptions = {},
+): UseFormIntelligenceResult<T> {
+  const {
+    onReport,
+    focusFirstError: shouldFocus = true,
+    announceErrors = true,
+  } = options;
+
+  const sessionStartedAt = useRef(Date.now());
+  const statsRef = useRef<Record<string, FieldFrictionStats>>({});
+  const refsRef = useRef<FieldRefMap<T>>({});
+  const submitAttempts = useRef(0);
+  const successfulSubmits = useRef(0);
+
+  const ensure = useCallback((field: T): FieldFrictionStats => {
+    const key = String(field);
+    if (!statsRef.current[key]) statsRef.current[key] = emptyStats();
+    return statsRef.current[key];
+  }, []);
+
+  const registerFieldRef = useCallback(
+    (field: T, ref: { current: TextInput | null } | TextInput | null) => {
+      refsRef.current[field] = ref;
+    },
+    [],
+  );
+
+  const trackFocus = useCallback(
+    (field: T) => {
+      const s = ensure(field);
+      s.focusCount += 1;
+      s.focusStartedAt = Date.now();
+      s.lastFocusedAt = s.focusStartedAt;
+    },
+    [ensure],
+  );
+
+  const trackBlur = useCallback(
+    (field: T) => {
+      const s = ensure(field);
+      s.blurCount += 1;
+      if (s.focusStartedAt) {
+        s.totalFocusMs += Date.now() - s.focusStartedAt;
+        s.focusStartedAt = undefined;
+      }
+    },
+    [ensure],
+  );
+
+  const trackChange = useCallback(
+    (field: T) => {
+      ensure(field).changeCount += 1;
+    },
+    [ensure],
+  );
+
+  const trackError = useCallback(
+    (field: T) => {
+      ensure(field).errorCount += 1;
+    },
+    [ensure],
+  );
+
+  const buildReport = useCallback((): FormHealthReport => {
+    const fields = { ...statsRef.current };
+    // Close any open focus sessions for accurate totals
+    const now = Date.now();
+    for (const s of Object.values(fields)) {
+      if (s.focusStartedAt) {
+        s.totalFocusMs += now - s.focusStartedAt;
+        s.focusStartedAt = undefined;
+      }
+    }
+
+    const mostFriction = Object.entries(fields)
+      .map(([field, s]) => ({
+        field,
+        score: s.errorCount * 3 + s.focusCount + Math.floor(s.changeCount / 10) + Math.floor(s.totalFocusMs / 5000),
+      }))
+      .sort((a, b) => b.score - a.score);
+
+    return {
+      sessionMs: now - sessionStartedAt.current,
+      submitAttempts: submitAttempts.current,
+      successfulSubmits: successfulSubmits.current,
+      fields,
+      mostFriction,
+      generatedAt: now,
+    };
+  }, []);
+
+  const onValidationResult = useCallback(
+    (valid: boolean, errors: Partial<Record<T, string | undefined>>, fieldOrder?: T[]) => {
+      submitAttempts.current += 1;
+
+      for (const [field, message] of Object.entries(errors) as Array<[T, string | undefined]>) {
+        if (message) trackError(field);
+      }
+
+      if (!valid) {
+        if (shouldFocus) {
+          focusFirstError(errors, refsRef.current, fieldOrder);
+        }
+        if (announceErrors) {
+          announceForAccessibility(buildValidationAnnouncement(errors));
+        }
+      }
+
+      onReport?.(buildReport());
+    },
+    [announceErrors, buildReport, onReport, shouldFocus, trackError],
+  );
+
+  const trackSubmitSuccess = useCallback(() => {
+    successfulSubmits.current += 1;
+    onReport?.(buildReport());
+  }, [buildReport, onReport]);
+
+  const getReport = useCallback(() => buildReport(), [buildReport]);
+
+  const flush = useCallback(() => {
+    const report = buildReport();
+    onReport?.(report);
+    return report;
+  }, [buildReport, onReport]);
+
+  const reset = useCallback(() => {
+    statsRef.current = {};
+    submitAttempts.current = 0;
+    successfulSubmits.current = 0;
+    sessionStartedAt.current = Date.now();
+  }, []);
+
+  return useMemo(
+    () => ({
+      registerFieldRef,
+      trackFocus,
+      trackBlur,
+      trackChange,
+      trackError,
+      onValidationResult,
+      trackSubmitSuccess,
+      getReport,
+      flush,
+      reset,
+    }),
+    [
+      registerFieldRef,
+      trackFocus,
+      trackBlur,
+      trackChange,
+      trackError,
+      onValidationResult,
+      trackSubmitSuccess,
+      getReport,
+      flush,
+      reset,
+    ],
+  );
+}

package/src/i18n/index.ts

@@ -0,0 +1,6 @@
+export {
+  validationMessageCatalogs,
+  getValidationMessages,
+  createValidationMessages,
+} from './messages';
+export type { FieldFlowLocale, FieldFlowValidationMessages } from './messages';

package/src/i18n/messages.ts

@@ -0,0 +1,101 @@
+export type FieldFlowLocale = 'en' | 'es' | 'fr' | 'de' | 'pt' | 'ar';
+
+export interface FieldFlowValidationMessages {
+  required: string;
+  email: string;
+  number: string;
+  phone: string;
+  minLength: (min: number) => string;
+  maxLength: (max: number) => string;
+  pattern: string;
+  invalid: string;
+}
+
+const en: FieldFlowValidationMessages = {
+  required: 'This field is required',
+  email: 'Enter a valid email address',
+  number: 'Enter a valid number',
+  phone: 'Enter a valid phone number',
+  minLength: min => `Must be at least ${min} characters`,
+  maxLength: max => `Must be at most ${max} characters`,
+  pattern: 'Invalid format',
+  invalid: 'Invalid',
+};
+
+const es: FieldFlowValidationMessages = {
+  required: 'Este campo es obligatorio',
+  email: 'Introduce un correo válido',
+  number: 'Introduce un número válido',
+  phone: 'Introduce un teléfono válido',
+  minLength: min => `Debe tener al menos ${min} caracteres`,
+  maxLength: max => `Debe tener como máximo ${max} caracteres`,
+  pattern: 'Formato no válido',
+  invalid: 'No válido',
+};
+
+const fr: FieldFlowValidationMessages = {
+  required: 'Ce champ est obligatoire',
+  email: 'Entrez une adresse e-mail valide',
+  number: 'Entrez un nombre valide',
+  phone: 'Entrez un numéro de téléphone valide',
+  minLength: min => `Doit contenir au moins ${min} caractères`,
+  maxLength: max => `Doit contenir au plus ${max} caractères`,
+  pattern: 'Format invalide',
+  invalid: 'Invalide',
+};
+
+const de: FieldFlowValidationMessages = {
+  required: 'Dieses Feld ist erforderlich',
+  email: 'Gültige E-Mail-Adresse eingeben',
+  number: 'Gültige Zahl eingeben',
+  phone: 'Gültige Telefonnummer eingeben',
+  minLength: min => `Mindestens ${min} Zeichen`,
+  maxLength: max => `Höchstens ${max} Zeichen`,
+  pattern: 'Ungültiges Format',
+  invalid: 'Ungültig',
+};
+
+const pt: FieldFlowValidationMessages = {
+  required: 'Este campo é obrigatório',
+  email: 'Introduza um e-mail válido',
+  number: 'Introduza um número válido',
+  phone: 'Introduza um telefone válido',
+  minLength: min => `Deve ter pelo menos ${min} caracteres`,
+  maxLength: max => `Deve ter no máximo ${max} caracteres`,
+  pattern: 'Formato inválido',
+  invalid: 'Inválido',
+};
+
+const ar: FieldFlowValidationMessages = {
+  required: 'هذا الحقل مطلوب',
+  email: 'أدخل بريداً إلكترونياً صالحاً',
+  number: 'أدخل رقماً صالحاً',
+  phone: 'أدخل رقم هاتف صالحاً',
+  minLength: min => `يجب أن يكون على الأقل ${min} أحرف`,
+  maxLength: max => `يجب أن يكون على الأكثر ${max} أحرف`,
+  pattern: 'تنسيق غير صالح',
+  invalid: 'غير صالح',
+};
+
+export const validationMessageCatalogs: Record<FieldFlowLocale, FieldFlowValidationMessages> = {
+  en,
+  es,
+  fr,
+  de,
+  pt,
+  ar,
+};
+
+export function getValidationMessages(
+  locale: FieldFlowLocale = 'en',
+): FieldFlowValidationMessages {
+  return validationMessageCatalogs[locale] ?? en;
+}
+
+/** Merge a partial catalog over a locale base (default English). */
+export function createValidationMessages(
+  overrides: Partial<FieldFlowValidationMessages>,
+  locale: FieldFlowLocale = 'en',
+): FieldFlowValidationMessages {
+  return { ...getValidationMessages(locale), ...overrides };
+}