rn-inputforge 0.3.1 → 0.5.0

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,
+  };
+}