rn-inputforge 0.4.0 → 0.5.1

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/useFieldFlowSubmitQueue.ts

@@ -0,0 +1,206 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+export interface FieldFlowSubmitJob<T = unknown> {
+  id: string;
+  payload: T;
+  createdAt: number;
+  attempts: number;
+  lastError?: string;
+}
+
+export interface FieldFlowSubmitQueueStorage {
+  getItem: (key: string) => Promise<string | null> | string | null;
+  setItem: (key: string, value: string) => Promise<void> | void;
+  removeItem: (key: string) => Promise<void> | void;
+}
+
+export interface UseFieldFlowSubmitQueueOptions<T> {
+  /** Unique storage key. */
+  key: string;
+  /** Persist queue (AsyncStorage / MMKV). Optional — in-memory if omitted. */
+  storage?: FieldFlowSubmitQueueStorage;
+  /** Actually send the payload. Throw / return false to keep in queue. */
+  submit: (payload: T) => Promise<void | boolean>;
+  /** Max attempts before parking as failed. Default: 5. */
+  maxAttempts?: number;
+  /** Auto-flush when online. Default: true. */
+  flushOnOnline?: boolean;
+  /** Called after a successful flush of one job. */
+  onSuccess?: (job: FieldFlowSubmitJob<T>) => void;
+  /** Called when a job exceeds maxAttempts. */
+  onGiveUp?: (job: FieldFlowSubmitJob<T>) => void;
+}
+
+export interface UseFieldFlowSubmitQueueResult<T> {
+  queue: FieldFlowSubmitJob<T>[];
+  pendingCount: number;
+  isFlushing: boolean;
+  isOnline: boolean;
+  /** Enqueue a payload (and try flush if online). */
+  enqueue: (payload: T) => Promise<string>;
+  /** Process the queue now. */
+  flush: () => Promise<void>;
+  clear: () => Promise<void>;
+  remove: (id: string) => Promise<void>;
+}
+
+function createId(): string {
+  return `ffq_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+}
+
+/**
+ * Offline-friendly submit queue — persist failed / offline form posts and retry.
+ */
+export function useFieldFlowSubmitQueue<T>({
+  key,
+  storage,
+  submit,
+  maxAttempts = 5,
+  flushOnOnline = true,
+  onSuccess,
+  onGiveUp,
+}: UseFieldFlowSubmitQueueOptions<T>): UseFieldFlowSubmitQueueResult<T> {
+  const [queue, setQueue] = useState<FieldFlowSubmitJob<T>[]>([]);
+  const [isFlushing, setIsFlushing] = useState(false);
+  const [isOnline, setIsOnline] = useState(true);
+  const queueRef = useRef(queue);
+  queueRef.current = queue;
+  const hydrated = useRef(false);
+
+  const persist = useCallback(
+    async (next: FieldFlowSubmitJob<T>[]) => {
+      setQueue(next);
+      queueRef.current = next;
+      if (!storage) return;
+      if (next.length === 0) await storage.removeItem(key);
+      else await storage.setItem(key, JSON.stringify(next));
+    },
+    [storage, key],
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      if (!storage) {
+        hydrated.current = true;
+        return;
+      }
+      try {
+        const raw = await storage.getItem(key);
+        if (cancelled || !raw) {
+          hydrated.current = true;
+          return;
+        }
+        const parsed = JSON.parse(raw) as FieldFlowSubmitJob<T>[];
+        if (!cancelled && Array.isArray(parsed)) {
+          setQueue(parsed);
+          queueRef.current = parsed;
+        }
+      } catch {
+        /* ignore corrupt */
+      } finally {
+        hydrated.current = true;
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [storage, key]);
+
+  useEffect(() => {
+    // NetInfo-free: use RN global if present, else assume online
+    type NetInfoLike = {
+      addEventListener?: (cb: (s: { isConnected?: boolean | null }) => void) => { remove: () => void };
+      fetch?: () => Promise<{ isConnected?: boolean | null }>;
+    };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const NetInfo = (globalThis as any).NetInfo as NetInfoLike | undefined;
+    if (!NetInfo?.addEventListener) return;
+
+    const sub = NetInfo.addEventListener(state => {
+      const online = state.isConnected !== false;
+      setIsOnline(online);
+    });
+    NetInfo.fetch?.().then(s => setIsOnline(s.isConnected !== false)).catch(() => undefined);
+    return () => sub?.remove();
+  }, []);
+
+  const flush = useCallback(async () => {
+    if (isFlushing) return;
+    setIsFlushing(true);
+    try {
+      let next = [...queueRef.current];
+      while (next.length > 0) {
+        const job = next[0];
+        try {
+          const result = await submit(job.payload);
+          if (result === false) throw new Error('Submit returned false');
+          onSuccess?.(job);
+          next = next.slice(1);
+          await persist(next);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : 'Submit failed';
+          const updated: FieldFlowSubmitJob<T> = {
+            ...job,
+            attempts: job.attempts + 1,
+            lastError: message,
+          };
+          if (updated.attempts >= maxAttempts) {
+            onGiveUp?.(updated);
+            next = next.slice(1);
+          } else {
+            next = [updated, ...next.slice(1)];
+          }
+          await persist(next);
+          break;
+        }
+      }
+    } finally {
+      setIsFlushing(false);
+    }
+  }, [isFlushing, submit, persist, maxAttempts, onSuccess, onGiveUp]);
+
+  useEffect(() => {
+    if (!flushOnOnline || !isOnline || !hydrated.current) return;
+    if (queueRef.current.length === 0) return;
+    void flush();
+  }, [isOnline, flushOnOnline, flush]);
+
+  const enqueue = useCallback(
+    async (payload: T) => {
+      const id = createId();
+      const job: FieldFlowSubmitJob<T> = {
+        id,
+        payload,
+        createdAt: Date.now(),
+        attempts: 0,
+      };
+      await persist([...queueRef.current, job]);
+      if (isOnline) void flush();
+      return id;
+    },
+    [persist, isOnline, flush],
+  );
+
+  const clear = useCallback(async () => {
+    await persist([]);
+  }, [persist]);
+
+  const remove = useCallback(
+    async (id: string) => {
+      await persist(queueRef.current.filter(j => j.id !== id));
+    },
+    [persist],
+  );
+
+  return {
+    queue,
+    pendingCount: queue.length,
+    isFlushing,
+    isOnline,
+    enqueue,
+    flush,
+    clear,
+    remove,
+  };
+}

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/hooks/useKeyboardManager.ts

@@ -13,7 +13,13 @@ export interface UseKeyboardManagerResult {
   unregisterField: (id: string) => void;
   /** Call from a field's onSubmitEditing to move focus to the next registered field, or submit if it's last. */
   focusNext: (id: string) => void;
+  /** Move focus to the previous field in `order` (no-op on first). */
+  focusPrevious: (id: string) => void;
   focusField: (id: string) => void;
+  /** Index helpers for keyboard toolbar enablement. */
+  getFieldIndex: (id: string) => number;
+  canGoPrevious: (id: string) => boolean;
+  canGoNext: (id: string) => boolean;
   /** Attach to the surrounding ScrollView so FieldFlow can scroll the active field into view. */
   scrollViewRef: React.RefObject<ScrollView | null>;
   /** returnKeyType to use for a field given its position ("next" for all but the last, "done" for the last). */
@@ -85,6 +91,22 @@ export function useKeyboardManager({
     [order, focusField, onSubmit],
   );
 
+  const focusPrevious = useCallback(
+    (id: string) => {
+      const currentIndex = order.indexOf(id);
+      const prevId = order[currentIndex - 1];
+      if (prevId) focusField(prevId);
+    },
+    [order, focusField],
+  );
+
+  const getFieldIndex = useCallback((id: string) => order.indexOf(id), [order]);
+  const canGoPrevious = useCallback((id: string) => order.indexOf(id) > 0, [order]);
+  const canGoNext = useCallback((id: string) => {
+    const i = order.indexOf(id);
+    return i >= 0 && i < order.length - 1;
+  }, [order]);
+
   const getReturnKeyType = useCallback(
     (id: string): 'next' | 'done' => {
       const isLast = order.indexOf(id) === order.length - 1;
@@ -97,7 +119,11 @@ export function useKeyboardManager({
     registerField,
     unregisterField,
     focusNext,
+    focusPrevious,
     focusField,
+    getFieldIndex,
+    canGoPrevious,
+    canGoNext,
     scrollViewRef,
     getReturnKeyType,
     onSubmit: () => onSubmit?.(),

package/src/hooks/useSmartPaste.ts

@@ -0,0 +1,33 @@
+import { useCallback } from 'react';
+import {
+  applySmartPaste,
+  routeSmartPaste,
+  type FieldFlowPasteResult,
+  type FieldFlowPasteTargets,
+} from '../paste/smartPaste';
+
+export interface UseSmartPasteOptions {
+  targets: FieldFlowPasteTargets;
+  minConfidence?: number;
+  onRouted?: (result: FieldFlowPasteResult) => void;
+}
+
+/**
+ * Hook helper for smart paste — call `handlePaste(text)` from Clipboard or a paste event.
+ */
+export function useSmartPaste({
+  targets,
+  minConfidence = 0.7,
+  onRouted,
+}: UseSmartPasteOptions) {
+  const handlePaste = useCallback(
+    (text: string) => {
+      const result = applySmartPaste(text, targets, minConfidence);
+      onRouted?.(result);
+      return result;
+    },
+    [targets, minConfidence, onRouted],
+  );
+
+  return { handlePaste, routeSmartPaste };
+}

package/src/i18n/index.ts

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