rn-inputforge 0.4.0 → 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 };
+}

package/src/index.ts

@@ -40,12 +40,97 @@ export type {
   FieldFlowDateTimeMode,
 } from './components/FieldFlowDateTimePicker';
 
+export { FieldFlowAffordance } from './components/FieldFlowAffordance';
+export type { FieldFlowAffordanceProps } from './components/FieldFlowAffordance';
+
+export { FieldFlowDraftBanner } from './components/FieldFlowDraftBanner';
+export type { FieldFlowDraftBannerProps } from './components/FieldFlowDraftBanner';
+
+export { FieldFlowTags } from './components/FieldFlowTags';
+export type { FieldFlowTagsProps } from './components/FieldFlowTags';
+
+export { FieldFlowPasswordStrength } from './components/FieldFlowPasswordStrength';
+export type { FieldFlowPasswordStrengthProps } from './components/FieldFlowPasswordStrength';
+
+export { FieldFlowSection } from './components/FieldFlowSection';
+export type { FieldFlowSectionProps } from './components/FieldFlowSection';
+
+export { FieldFlowSegmented } from './components/FieldFlowSegmented';
+export type { FieldFlowSegmentedProps } from './components/FieldFlowSegmented';
+
+export { FieldFlowStepper } from './components/FieldFlowStepper';
+export type { FieldFlowStepperProps, FieldFlowStepRenderContext } from './components/FieldFlowStepper';
+
+export { FieldFlowPhone } from './components/FieldFlowPhone';
+export type { FieldFlowPhoneProps, FieldFlowPhoneValue } from './components/FieldFlowPhone';
+
+export { FieldFlowUpload } from './components/FieldFlowUpload';
+export type {
+  FieldFlowUploadProps,
+  FieldFlowUploadFile,
+  FieldFlowUploadPicker,
+} from './components/FieldFlowUpload';
+
+export { FieldFlowTypeahead } from './components/FieldFlowTypeahead';
+export type { FieldFlowTypeaheadProps, FieldFlowTypeaheadFetcher } from './components/FieldFlowTypeahead';
+
+export { FieldFlowRating } from './components/FieldFlowRating';
+export type { FieldFlowRatingProps } from './components/FieldFlowRating';
+
+export { FieldFlowSlider } from './components/FieldFlowSlider';
+export type { FieldFlowSliderProps } from './components/FieldFlowSlider';
+
+export { FieldFlowNumberStepper } from './components/FieldFlowNumberStepper';
+export type { FieldFlowNumberStepperProps } from './components/FieldFlowNumberStepper';
+
+export { FieldFlowCreditCard } from './components/FieldFlowCreditCard';
+export type { FieldFlowCreditCardProps, FieldFlowCreditCardValue } from './components/FieldFlowCreditCard';
+
+export { FieldFlowSignature } from './components/FieldFlowSignature';
+export type {
+  FieldFlowSignatureProps,
+  FieldFlowSignatureValue,
+  FieldFlowStroke,
+  FieldFlowPoint,
+} from './components/FieldFlowSignature';
+
+// Adapters (optional peers: react-hook-form)
+export {
+  FieldFlowController,
+  FieldFlowTagsController,
+  mapRhfToFieldFlowProps,
+} from './adapters';
+export type {
+  FieldFlowControllerProps,
+  FieldFlowTagsControllerProps,
+} from './adapters';
+
 // Theming
-export { FieldFlowThemeProvider, useFieldFlowTheme, defaultTheme, darkTheme } from './theme';
-export type { FieldFlowThemeProviderProps } from './theme';
+export {
+  FieldFlowThemeProvider,
+  useFieldFlowTheme,
+  defaultTheme,
+  darkTheme,
+  themePresets,
+  getThemePreset,
+} from './theme';
+export type { FieldFlowThemeProviderProps, FieldFlowThemePresetName } from './theme';
+
+// Motion
+export { useFieldMotion, useReducedMotion } from './motion';
+export type { UseFieldMotionOptions, UseFieldMotionResult } from './motion';
 
 // Hooks
-export { useFieldFlowForm, useKeyboardManager, useFieldState } from './hooks';
+export {
+  useFieldFlowForm,
+  useKeyboardManager,
+  useFieldState,
+  useFormIntelligence,
+  useFieldFlowArray,
+  useFieldFlowDraft,
+  useFieldFlowSteps,
+  useFieldFlowDirtyGuard,
+} from './hooks';
 export type {
   UseFieldFlowFormOptions,
   UseFieldFlowFormResult,
@@ -53,11 +138,43 @@ export type {
   AsyncFieldValidator,
   AsyncFieldValidators,
   CrossFieldRule,
+  FieldConditionFn,
+  FieldConditionConfig,
+  FieldConditions,
+  FieldVisibilityState,
   UseKeyboardManagerOptions,
   UseKeyboardManagerResult,
   UseFieldStateOptions,
+  UseFormIntelligenceResult,
+  UseFieldFlowArrayOptions,
+  UseFieldFlowArrayResult,
+  FieldFlowDraftStorage,
+  FieldFlowDraftPayload,
+  UseFieldFlowDraftOptions,
+  UseFieldFlowDraftResult,
+  FieldFlowStepDefinition,
+  UseFieldFlowStepsOptions,
+  UseFieldFlowStepsResult,
+  UseFieldFlowDirtyGuardOptions,
+  UseFieldFlowDirtyGuardResult,
 } from './hooks';
 
+// i18n
+export {
+  validationMessageCatalogs,
+  getValidationMessages,
+  createValidationMessages,
+} from './i18n';
+export type { FieldFlowLocale, FieldFlowValidationMessages } from './i18n';
+
+// Phone helpers
+export {
+  DEFAULT_COUNTRY_DIALS,
+  findCountryByCode,
+  composeE164,
+} from './utils/phoneCountries';
+export type { FieldFlowCountryDial } from './utils/phoneCountries';
+
 // Validation
 export {
   useValidation,
@@ -93,6 +210,47 @@ export {
 } from './utils/masks';
 export type { FieldFlowMaskType, MaskResult, ApplyMaskOptions } from './utils/masks';
 
+// Affordance helpers
+export {
+  applyEmailDomainSuggestion,
+  applyPhoneDialSuggestion,
+  applyCurrencySymbolSuggestion,
+  applyAffordanceSuggestion,
+  resolveAffordanceChips,
+  emailDomainsToChips,
+  affordanceKindFromFieldType,
+  DEFAULT_EMAIL_DOMAINS,
+  DEFAULT_PHONE_DIAL_CODES,
+  DEFAULT_CURRENCY_SYMBOLS,
+} from './utils/affordance';
+export type { FieldFlowAffordanceKind, FieldFlowAffordanceChip } from './utils/affordance';
+
+// Password strength
+export {
+  evaluatePasswordStrength,
+  DEFAULT_PASSWORD_RULES,
+  PASSWORD_STRENGTH_COLORS,
+} from './utils/passwordStrength';
+export type {
+  PasswordStrengthLevel,
+  PasswordStrengthRule,
+  PasswordStrengthResult,
+} from './utils/passwordStrength';
+
+// Form intelligence / a11y
+export {
+  focusFirstError,
+  announceForAccessibility,
+  buildValidationAnnouncement,
+  setAccessibilityFocus,
+} from './intelligence';
+export type {
+  FieldRefMap,
+  FieldFrictionStats,
+  FormHealthReport,
+  FormIntelligenceOptions,
+} from './intelligence';
+
 // Icons
 export { FieldFlowIcon, renderFieldFlowIcon } from './icons';
 export type { FieldFlowIconName, FieldFlowIconProps, FieldFlowIconSource } from './icons';