rn-inputforge 0.4.0 → 0.5.1

package/src/hooks/useFieldFlowArray.ts

@@ -0,0 +1,153 @@
+import { useCallback, useMemo, useState } from 'react';
+
+export interface UseFieldFlowArrayOptions<TItem> {
+  /** Initial rows. Default: `[]`. */
+  initialItems?: TItem[];
+  /** Factory for a blank row when calling `append()` without an argument. */
+  createItem: () => TItem;
+  /** Hard cap on rows. `append` becomes a no-op at the limit. */
+  max?: number;
+  /** Minimum rows. `remove` is blocked when at the floor. Default: 0. */
+  min?: number;
+}
+
+export interface UseFieldFlowArrayResult<TItem> {
+  items: TItem[];
+  /** Number of rows. */
+  length: number;
+  /** True when `max` is set and reached. */
+  isMax: boolean;
+  /** True when at `min` rows. */
+  isMin: boolean;
+  setItems: (items: TItem[] | ((prev: TItem[]) => TItem[])) => void;
+  /** Append a row (or `createItem()`). Returns the new index, or `-1` if blocked. */
+  append: (item?: TItem) => number;
+  /** Remove by index. Returns false if blocked by `min`. */
+  remove: (index: number) => boolean;
+  /** Replace a single row. */
+  update: (index: number, item: TItem | ((prev: TItem) => TItem)) => void;
+  /** Swap two indices. */
+  move: (from: number, to: number) => void;
+  /** Insert at index (clamped). */
+  insert: (index: number, item?: TItem) => void;
+  clear: () => void;
+  reset: () => void;
+}
+
+/**
+ * Manage dynamic / repeatable field groups (addresses, line items, guests, …)
+ * alongside FieldFlow inputs. Pure state — no UI assumptions.
+ *
+ * @example
+ * const guests = useFieldFlowArray({
+ *   createItem: () => ({ name: '', email: '' }),
+ *   min: 1,
+ *   max: 5,
+ * });
+ *
+ * guests.items.map((guest, i) => (
+ *   <FieldFlowInput
+ *     key={i}
+ *     label={`Guest ${i + 1}`}
+ *     value={guest.name}
+ *     onChangeText={name => guests.update(i, g => ({ ...g, name }))}
+ *   />
+ * ));
+ */
+export function useFieldFlowArray<TItem>({
+  initialItems = [],
+  createItem,
+  max,
+  min = 0,
+}: UseFieldFlowArrayOptions<TItem>): UseFieldFlowArrayResult<TItem> {
+  const [items, setItems] = useState<TItem[]>(initialItems);
+  const initialRef = useMemo(() => initialItems, []); // freeze initial for reset
+
+  const isMax = max !== undefined && items.length >= max;
+  const isMin = items.length <= min;
+
+  const append = useCallback(
+    (item?: TItem): number => {
+      let nextIndex = -1;
+      setItems(prev => {
+        if (max !== undefined && prev.length >= max) return prev;
+        const next = [...prev, item ?? createItem()];
+        nextIndex = next.length - 1;
+        return next;
+      });
+      return nextIndex;
+    },
+    [createItem, max],
+  );
+
+  const remove = useCallback(
+    (index: number): boolean => {
+      let removed = false;
+      setItems(prev => {
+        if (prev.length <= min) return prev;
+        if (index < 0 || index >= prev.length) return prev;
+        removed = true;
+        return prev.filter((_, i) => i !== index);
+      });
+      return removed;
+    },
+    [min],
+  );
+
+  const update = useCallback((index: number, item: TItem | ((prev: TItem) => TItem)) => {
+    setItems(prev => {
+      if (index < 0 || index >= prev.length) return prev;
+      const next = [...prev];
+      next[index] = typeof item === 'function' ? (item as (p: TItem) => TItem)(prev[index]) : item;
+      return next;
+    });
+  }, []);
+
+  const move = useCallback((from: number, to: number) => {
+    setItems(prev => {
+      if (from < 0 || to < 0 || from >= prev.length || to >= prev.length || from === to) {
+        return prev;
+      }
+      const next = [...prev];
+      const [row] = next.splice(from, 1);
+      next.splice(to, 0, row);
+      return next;
+    });
+  }, []);
+
+  const insert = useCallback(
+    (index: number, item?: TItem) => {
+      setItems(prev => {
+        if (max !== undefined && prev.length >= max) return prev;
+        const next = [...prev];
+        const at = Math.max(0, Math.min(index, next.length));
+        next.splice(at, 0, item ?? createItem());
+        return next;
+      });
+    },
+    [createItem, max],
+  );
+
+  const clear = useCallback(() => {
+    setItems(min > 0 ? Array.from({ length: min }, () => createItem()) : []);
+  }, [createItem, min]);
+
+  const reset = useCallback(() => {
+    setItems(initialRef);
+  }, [initialRef]);
+
+  return {
+    items,
+    length: items.length,
+    isMax,
+    isMin,
+    setItems,
+    append,
+    remove,
+    update,
+    move,
+    insert,
+    clear,
+    reset,
+  };
+}

package/src/hooks/useFieldFlowCompleteness.ts

@@ -0,0 +1,69 @@
+import { useMemo } from 'react';
+
+export interface UseFieldFlowCompletenessOptions<T extends Record<string, string>> {
+  values: T;
+  /** Required field keys (or dynamic list). */
+  requiredFields: (keyof T)[];
+  /** Optional: treat as filled when custom predicate returns true. */
+  isFilled?: (field: keyof T, value: string, values: T) => boolean;
+  /** Seconds users typically need per empty required field (for estimate). Default: 8. */
+  secondsPerField?: number;
+}
+
+export interface UseFieldFlowCompletenessResult<T extends Record<string, string>> {
+  total: number;
+  filled: number;
+  remaining: number;
+  /** 0–1 */
+  progress: number;
+  /** 0–100 */
+  percent: number;
+  remainingFields: (keyof T)[];
+  filledFields: (keyof T)[];
+  isComplete: boolean;
+  /** Rough seconds left based on empty required fields. */
+  estimatedSecondsLeft: number;
+}
+
+function defaultFilled(value: string): boolean {
+  return value.trim().length > 0;
+}
+
+/**
+ * Live form completeness for required fields — powers `FieldFlowCompleteness`.
+ */
+export function useFieldFlowCompleteness<T extends Record<string, string>>({
+  values,
+  requiredFields,
+  isFilled,
+  secondsPerField = 8,
+}: UseFieldFlowCompletenessOptions<T>): UseFieldFlowCompletenessResult<T> {
+  return useMemo(() => {
+    const filledFields: (keyof T)[] = [];
+    const remainingFields: (keyof T)[] = [];
+
+    for (const field of requiredFields) {
+      const value = values[field] ?? '';
+      const ok = isFilled ? isFilled(field, value, values) : defaultFilled(value);
+      if (ok) filledFields.push(field);
+      else remainingFields.push(field);
+    }
+
+    const total = requiredFields.length;
+    const filled = filledFields.length;
+    const remaining = remainingFields.length;
+    const progress = total === 0 ? 1 : filled / total;
+
+    return {
+      total,
+      filled,
+      remaining,
+      progress,
+      percent: Math.round(progress * 100),
+      remainingFields,
+      filledFields,
+      isComplete: remaining === 0,
+      estimatedSecondsLeft: remaining * secondsPerField,
+    };
+  }, [values, requiredFields, isFilled, secondsPerField]);
+}

package/src/hooks/useFieldFlowDirtyGuard.ts

@@ -0,0 +1,70 @@
+import { useCallback, useEffect } from 'react';
+import { Alert, BackHandler, Platform } from 'react-native';
+
+export interface UseFieldFlowDirtyGuardOptions {
+  /** When true, leaving the screen should confirm. */
+  isDirty: boolean;
+  enabled?: boolean;
+  title?: string;
+  message?: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  /** Android hardware back — intercept when dirty. Default: true. */
+  interceptAndroidBack?: boolean;
+  /** Called when the user confirms discard. */
+  onDiscard?: () => void;
+}
+
+export interface UseFieldFlowDirtyGuardResult {
+  /**
+   * Call before navigating away. Returns true if navigation may proceed.
+   * Shows a confirm alert when the form is dirty.
+   */
+  confirmIfDirty: () => Promise<boolean>;
+}
+
+/**
+ * Warns before leaving a dirty form (Android back + imperative `confirmIfDirty`).
+ * For React Navigation, call `confirmIfDirty` inside a `beforeRemove` listener.
+ */
+export function useFieldFlowDirtyGuard({
+  isDirty,
+  enabled = true,
+  title = 'Discard changes?',
+  message = 'You have unsaved changes. Leave without saving?',
+  confirmLabel = 'Discard',
+  cancelLabel = 'Stay',
+  interceptAndroidBack = true,
+  onDiscard,
+}: UseFieldFlowDirtyGuardOptions): UseFieldFlowDirtyGuardResult {
+  const confirmIfDirty = useCallback((): Promise<boolean> => {
+    if (!enabled || !isDirty) return Promise.resolve(true);
+
+    return new Promise(resolve => {
+      Alert.alert(title, message, [
+        { text: cancelLabel, style: 'cancel', onPress: () => resolve(false) },
+        {
+          text: confirmLabel,
+          style: 'destructive',
+          onPress: () => {
+            onDiscard?.();
+            resolve(true);
+          },
+        },
+      ]);
+    });
+  }, [enabled, isDirty, title, message, confirmLabel, cancelLabel, onDiscard]);
+
+  useEffect(() => {
+    if (!enabled || !interceptAndroidBack || Platform.OS !== 'android') return;
+
+    const sub = BackHandler.addEventListener('hardwareBackPress', () => {
+      if (!isDirty) return false;
+      void confirmIfDirty();
+      return true;
+    });
+    return () => sub.remove();
+  }, [enabled, interceptAndroidBack, isDirty, confirmIfDirty]);
+
+  return { confirmIfDirty };
+}

package/src/hooks/useFieldFlowDraft.ts

@@ -0,0 +1,221 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/**
+ * Minimal async key-value storage. Pass AsyncStorage, MMKV wrapper, or any custom backend.
+ *
+ * @example
+ * import AsyncStorage from '@react-native-async-storage/async-storage';
+ * const storage = {
+ *   getItem: (k) => AsyncStorage.getItem(k),
+ *   setItem: (k, v) => AsyncStorage.setItem(k, v),
+ *   removeItem: (k) => AsyncStorage.removeItem(k),
+ * };
+ */
+export interface FieldFlowDraftStorage {
+  getItem: (key: string) => Promise<string | null>;
+  setItem: (key: string, value: string) => Promise<void>;
+  removeItem: (key: string) => Promise<void>;
+}
+
+export interface FieldFlowDraftPayload<T extends Record<string, string>> {
+  values: T;
+  savedAt: number;
+  version: 1;
+}
+
+export interface UseFieldFlowDraftOptions<T extends Record<string, string>> {
+  /** Unique storage key, e.g. `signup-form-v1`. */
+  key: string;
+  storage: FieldFlowDraftStorage;
+  /** Live form values to persist. */
+  values: T;
+  /** Apply restored values (typically `form` helpers or `setValues`). */
+  onRestore: (values: T) => void;
+  /** Fields never written to storage (passwords, OTPs, card numbers). */
+  exclude?: (keyof T)[];
+  /** Debounce writes while typing. Default: 600ms. */
+  debounceMs?: number;
+  /** Discard drafts older than this many ms. Default: 7 days. */
+  ttlMs?: number;
+  /** When true (default), auto-load a valid draft on mount and surface `hasDraft`. */
+  autoLoad?: boolean;
+  /** Disable all persistence (useful in tests). */
+  enabled?: boolean;
+}
+
+export interface UseFieldFlowDraftResult<T extends Record<string, string>> {
+  /** True once the initial storage read has finished. */
+  ready: boolean;
+  /** A valid draft exists that has not yet been resumed or discarded. */
+  hasDraft: boolean;
+  /** Timestamp of the pending draft, if any. */
+  draftSavedAt: number | null;
+  /** Snapshot of the pending draft values (before resume). */
+  draftValues: T | null;
+  /** Apply the pending draft via `onRestore` and clear the banner state. */
+  resume: () => void;
+  /** Delete the draft and hide the banner. */
+  discard: () => Promise<void>;
+  /** Force an immediate save of current values. */
+  saveNow: () => Promise<void>;
+  /** Clear storage for this key. */
+  clear: () => Promise<void>;
+}
+
+function pickPersisted<T extends Record<string, string>>(
+  values: T,
+  exclude?: (keyof T)[],
+): T {
+  if (!exclude?.length) return { ...values };
+  const next = { ...values };
+  for (const key of exclude) {
+    delete (next as Record<string, string>)[key as string];
+  }
+  return next;
+}
+
+/**
+ * Debounced draft persistence for FieldFlow forms. Storage is injected so the
+ * package stays free of native / peer storage dependencies.
+ */
+export function useFieldFlowDraft<T extends Record<string, string>>({
+  key,
+  storage,
+  values,
+  onRestore,
+  exclude,
+  debounceMs = 600,
+  ttlMs = 7 * 24 * 60 * 60 * 1000,
+  autoLoad = true,
+  enabled = true,
+}: UseFieldFlowDraftOptions<T>): UseFieldFlowDraftResult<T> {
+  const [ready, setReady] = useState(false);
+  const [hasDraft, setHasDraft] = useState(false);
+  const [draftSavedAt, setDraftSavedAt] = useState<number | null>(null);
+  const [draftValues, setDraftValues] = useState<T | null>(null);
+
+  const valuesRef = useRef(values);
+  valuesRef.current = values;
+  const skipNextSave = useRef(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const onRestoreRef = useRef(onRestore);
+  onRestoreRef.current = onRestore;
+
+  const write = useCallback(
+    async (nextValues: T) => {
+      if (!enabled) return;
+      const payload: FieldFlowDraftPayload<T> = {
+        values: pickPersisted(nextValues, exclude),
+        savedAt: Date.now(),
+        version: 1,
+      };
+      await storage.setItem(key, JSON.stringify(payload));
+    },
+    [enabled, exclude, key, storage],
+  );
+
+  const clear = useCallback(async () => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    await storage.removeItem(key);
+    setHasDraft(false);
+    setDraftSavedAt(null);
+    setDraftValues(null);
+  }, [key, storage]);
+
+  const discard = useCallback(async () => {
+    await clear();
+  }, [clear]);
+
+  const resume = useCallback(() => {
+    if (!draftValues) return;
+    skipNextSave.current = true;
+    onRestoreRef.current(draftValues);
+    setHasDraft(false);
+    setDraftValues(null);
+    setDraftSavedAt(null);
+  }, [draftValues]);
+
+  const saveNow = useCallback(async () => {
+    await write(valuesRef.current);
+  }, [write]);
+
+  // Initial hydrate
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      if (!enabled || !autoLoad) {
+        setReady(true);
+        return;
+      }
+      try {
+        const raw = await storage.getItem(key);
+        if (cancelled) return;
+        if (!raw) {
+          setReady(true);
+          return;
+        }
+        const parsed = JSON.parse(raw) as FieldFlowDraftPayload<T>;
+        if (!parsed?.values || typeof parsed.savedAt !== 'number') {
+          await storage.removeItem(key);
+          setReady(true);
+          return;
+        }
+        if (Date.now() - parsed.savedAt > ttlMs) {
+          await storage.removeItem(key);
+          setReady(true);
+          return;
+        }
+        // Only surface banner if draft differs from current values in a meaningful way
+        const persisted = pickPersisted(parsed.values, exclude);
+        const current = pickPersisted(valuesRef.current, exclude);
+        const differs = JSON.stringify(persisted) !== JSON.stringify(current);
+        if (differs) {
+          setDraftValues(parsed.values);
+          setDraftSavedAt(parsed.savedAt);
+          setHasDraft(true);
+        }
+      } catch {
+        // Corrupt payload — wipe and continue
+        try {
+          await storage.removeItem(key);
+        } catch {
+          /* ignore */
+        }
+      } finally {
+        if (!cancelled) setReady(true);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+    // Intentionally once per key/enabled
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, enabled, autoLoad]);
+
+  // Debounced autosave
+  useEffect(() => {
+    if (!enabled || !ready) return;
+    if (skipNextSave.current) {
+      skipNextSave.current = false;
+      return;
+    }
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(() => {
+      void write(valuesRef.current);
+    }, debounceMs);
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, [values, enabled, ready, debounceMs, write]);
+
+  return {
+    ready,
+    hasDraft,
+    draftSavedAt,
+    draftValues,
+    resume,
+    discard,
+    saveNow,
+    clear,
+  };
+}