rn-inputforge 0.5.0 → 0.5.1

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

@@ -94,6 +94,47 @@ export type {
   FieldFlowPoint,
 } from './components/FieldFlowSignature';
 
+export { FieldFlowCompleteness } from './components/FieldFlowCompleteness';
+export type { FieldFlowCompletenessProps } from './components/FieldFlowCompleteness';
+
+export { FieldFlowAuthActions } from './components/FieldFlowAuthActions';
+export type {
+  FieldFlowAuthActionsProps,
+  FieldFlowAuthAction,
+  FieldFlowAuthProvider,
+} from './components/FieldFlowAuthActions';
+
+export {
+  FieldFlowKeyboardToolbar,
+  FIELD_FLOW_KEYBOARD_TOOLBAR_ID,
+} from './components/FieldFlowKeyboardToolbar';
+export type { FieldFlowKeyboardToolbarProps } from './components/FieldFlowKeyboardToolbar';
+
+export { FieldFlowA11yAudit } from './components/FieldFlowA11yAudit';
+export type { FieldFlowA11yAuditProps } from './components/FieldFlowA11yAudit';
+
+export { FieldFlowInlineAlert } from './components/FieldFlowInlineAlert';
+export type { FieldFlowInlineAlertProps, FieldFlowAlertTone } from './components/FieldFlowInlineAlert';
+
+export { FieldFlowSkeleton } from './components/FieldFlowSkeleton';
+export type { FieldFlowSkeletonProps } from './components/FieldFlowSkeleton';
+
+export { FieldFlowFormHeader } from './components/FieldFlowFormHeader';
+export type { FieldFlowFormHeaderProps } from './components/FieldFlowFormHeader';
+
+export { FieldFlowInfoTip } from './components/FieldFlowInfoTip';
+export type { FieldFlowInfoTipProps } from './components/FieldFlowInfoTip';
+
+export { FieldFlowSchemaForm } from './schema';
+export type {
+  FieldFlowSchemaFormProps,
+  FieldFlowSchemaShowWhenFn,
+  FieldFlowFormSchema,
+  FieldFlowSchemaField,
+  FieldFlowSchemaFieldType,
+  FieldFlowSchemaSection,
+} from './schema';
+
 // Adapters (optional peers: react-hook-form)
 export {
   FieldFlowController,
@@ -113,6 +154,9 @@ export {
   darkTheme,
   themePresets,
   getThemePreset,
+  applyAppearance,
+  defaultAppearance,
+  surfaceShadow,
 } from './theme';
 export type { FieldFlowThemeProviderProps, FieldFlowThemePresetName } from './theme';
 
@@ -130,6 +174,9 @@ export {
   useFieldFlowDraft,
   useFieldFlowSteps,
   useFieldFlowDirtyGuard,
+  useFieldFlowCompleteness,
+  useFieldFlowSubmitQueue,
+  useSmartPaste,
 } from './hooks';
 export type {
   UseFieldFlowFormOptions,
@@ -157,8 +204,45 @@ export type {
   UseFieldFlowStepsResult,
   UseFieldFlowDirtyGuardOptions,
   UseFieldFlowDirtyGuardResult,
+  UseFieldFlowCompletenessOptions,
+  UseFieldFlowCompletenessResult,
+  FieldFlowSubmitJob,
+  FieldFlowSubmitQueueStorage,
+  UseFieldFlowSubmitQueueOptions,
+  UseFieldFlowSubmitQueueResult,
+  UseSmartPasteOptions,
 } from './hooks';
 
+// Autofill
+export {
+  getAutofillProps,
+  autofillRoleFromFieldType,
+  autofillProfiles,
+} from './autofill';
+export type {
+  FieldFlowAutofillRole,
+  FieldFlowAutofillProps,
+  FieldFlowAutofillProfileName,
+} from './autofill';
+
+// Smart paste
+export { routeSmartPaste, applySmartPaste } from './paste';
+export type {
+  FieldFlowPasteKind,
+  FieldFlowPasteResult,
+  FieldFlowAddressPaste,
+  FieldFlowPasteTargets,
+} from './paste';
+
+// A11y audit
+export { runA11yAudit } from './a11y';
+export type {
+  FieldFlowA11ySeverity,
+  FieldFlowA11yIssue,
+  FieldFlowA11yFieldSnapshot,
+  FieldFlowA11yAuditInput,
+} from './a11y';
+
 // i18n
 export {
   validationMessageCatalogs,
@@ -269,5 +353,11 @@ export type {
   FieldFlowTypography,
   FieldFlowAnimationConfig,
   FieldFlowTheme,
+  FieldFlowAppearance,
+  FieldFlowDensity,
+  FieldFlowControlSize,
+  FieldFlowSurface,
+  FieldFlowShape,
+  FieldFlowFocusRing,
   DeepPartial,
 } from './types';

package/src/paste/index.ts

@@ -0,0 +1,7 @@
+export { routeSmartPaste, applySmartPaste } from './smartPaste';
+export type {
+  FieldFlowPasteKind,
+  FieldFlowPasteResult,
+  FieldFlowAddressPaste,
+  FieldFlowPasteTargets,
+} from './smartPaste';

package/src/paste/smartPaste.ts

@@ -0,0 +1,132 @@
+export type FieldFlowPasteKind =
+  | 'otp'
+  | 'card'
+  | 'email'
+  | 'phone'
+  | 'address'
+  | 'url'
+  | 'unknown';
+
+export interface FieldFlowAddressPaste {
+  street?: string;
+  city?: string;
+  state?: string;
+  postalCode?: string;
+  country?: string;
+  raw: string;
+}
+
+export interface FieldFlowPasteResult {
+  kind: FieldFlowPasteKind;
+  /** Primary value for a single target field. */
+  value: string;
+  /** Digits-only for OTP / card / phone when applicable. */
+  raw?: string;
+  address?: FieldFlowAddressPaste;
+  confidence: number;
+}
+
+function digitsOnly(s: string): string {
+  return s.replace(/\D/g, '');
+}
+
+/**
+ * Classify clipboard / pasted text and extract a structured value.
+ * Pure — no Clipboard permission required; call from `onPaste` or after reading clipboard.
+ */
+export function routeSmartPaste(text: string): FieldFlowPasteResult {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return { kind: 'unknown', value: '', confidence: 0 };
+  }
+
+  const digits = digitsOnly(trimmed);
+
+  // OTP: 4–8 digits, little else
+  if (/^\d{4,8}$/.test(digits) && digits.length === trimmed.replace(/\s/g, '').length) {
+    return { kind: 'otp', value: digits, raw: digits, confidence: 0.95 };
+  }
+
+  // Card: 13–19 digits (spaces/dashes ok)
+  if (digits.length >= 13 && digits.length <= 19 && /^[\d\s-]+$/.test(trimmed)) {
+    return { kind: 'card', value: digits, raw: digits, confidence: 0.9 };
+  }
+
+  // Email
+  if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(trimmed)) {
+    return { kind: 'email', value: trimmed.toLowerCase(), confidence: 0.98 };
+  }
+
+  // URL
+  if (/^https?:\/\//i.test(trimmed) || /^www\./i.test(trimmed)) {
+    return {
+      kind: 'url',
+      value: trimmed.startsWith('http') ? trimmed : `https://${trimmed}`,
+      confidence: 0.9,
+    };
+  }
+
+  // Phone: 7–15 digits with optional + and punctuation
+  if (
+    digits.length >= 7 &&
+    digits.length <= 15 &&
+    /^[+]?[\d\s().-]{7,22}$/.test(trimmed) &&
+    !/[a-zA-Z]{3,}/.test(trimmed)
+  ) {
+    return { kind: 'phone', value: trimmed, raw: digits, confidence: 0.85 };
+  }
+
+  // Multi-line address-ish
+  const lines = trimmed
+    .split(/\r?\n/)
+    .map(l => l.trim())
+    .filter(Boolean);
+  if (lines.length >= 2) {
+    const postalMatch = trimmed.match(/\b([A-Z]{1,2}\d[A-Z\d]?\s*\d[A-Z]{2}|\d{5}(?:-\d{4})?)\b/i);
+    const address: FieldFlowAddressPaste = {
+      street: lines[0],
+      city: lines[1]?.replace(/,.*$/, '').trim(),
+      state: lines[1]?.includes(',')
+        ? lines[1].split(',')[1]?.trim().split(/\s+/)[0]
+        : undefined,
+      postalCode: postalMatch?.[1],
+      raw: trimmed,
+    };
+    return {
+      kind: 'address',
+      value: lines[0],
+      address,
+      confidence: 0.7,
+    };
+  }
+
+  return { kind: 'unknown', value: trimmed, confidence: 0.2 };
+}
+
+export type FieldFlowPasteTargets = Partial<
+  Record<FieldFlowPasteKind, (result: FieldFlowPasteResult) => void>
+> & {
+  /** Called when kind is address and you want field-level writes. */
+  addressFields?: (address: FieldFlowAddressPaste) => void;
+};
+
+/**
+ * Route paste into field setters. Returns true if a handler ran with confidence ≥ minConfidence.
+ */
+export function applySmartPaste(
+  text: string,
+  targets: FieldFlowPasteTargets,
+  minConfidence = 0.7,
+): FieldFlowPasteResult {
+  const result = routeSmartPaste(text);
+  if (result.confidence < minConfidence) return result;
+
+  if (result.kind === 'address' && result.address && targets.addressFields) {
+    targets.addressFields(result.address);
+    return result;
+  }
+
+  const handler = targets[result.kind];
+  if (handler) handler(result);
+  return result;
+}