rn-inputforge 0.4.0 → 0.5.0

package/src/intelligence/formAccessibility.ts

@@ -0,0 +1,87 @@
+import { AccessibilityInfo, findNodeHandle, type TextInput } from 'react-native';
+
+export type FieldRefMap<T extends string = string> = Partial<
+  Record<T, { current: TextInput | null } | TextInput | null>
+>;
+
+function resolveNode(ref: FieldRefMap[string]): TextInput | null {
+  if (!ref) return null;
+  if (typeof ref === 'object' && 'current' in ref) return ref.current ?? null;
+  return ref;
+}
+
+/**
+ * Focus the first field (in `order` or object key order) that has an error.
+ * Returns the field key that was focused, or `undefined` if none.
+ */
+export function focusFirstError<T extends string>(
+  errors: Partial<Record<T, string | undefined>>,
+  refs: FieldRefMap<T>,
+  order?: T[],
+): T | undefined {
+  const keys = order ?? (Object.keys(errors) as T[]);
+  for (const key of keys) {
+    if (!errors[key]) continue;
+    const node = resolveNode(refs[key]);
+    if (node && typeof node.focus === 'function') {
+      node.focus();
+      return key;
+    }
+  }
+  // Fallback: any field with an error that has a ref, even if not in order
+  for (const key of Object.keys(errors) as T[]) {
+    if (!errors[key]) continue;
+    const node = resolveNode(refs[key]);
+    if (node && typeof node.focus === 'function') {
+      node.focus();
+      return key;
+    }
+  }
+  return undefined;
+}
+
+/** Announce a short message to VoiceOver / TalkBack when available. */
+export function announceForAccessibility(message: string): void {
+  if (!message) return;
+  try {
+    AccessibilityInfo.announceForAccessibility(message);
+  } catch {
+    // Older RN / platforms without announce support — silently ignore.
+  }
+}
+
+/**
+ * Build a concise announcement for failed validation, e.g.
+ * "Form has 2 errors. Email is required."
+ */
+export function buildValidationAnnouncement(
+  errors: Partial<Record<string, string | undefined>>,
+): string {
+  const entries = Object.entries(errors).filter(([, msg]) => Boolean(msg)) as Array<
+    [string, string]
+  >;
+  if (entries.length === 0) return '';
+  const [firstField, firstMessage] = entries[0];
+  if (entries.length === 1) {
+    return `${formatFieldName(firstField)}: ${firstMessage}`;
+  }
+  return `Form has ${entries.length} errors. ${formatFieldName(firstField)}: ${firstMessage}`;
+}
+
+function formatFieldName(field: string): string {
+  return field
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/[_-]/g, ' ')
+    .replace(/^\w/, c => c.toUpperCase())
+    .trim();
+}
+
+/** Best-effort: mark a native view as accessibility-focused (Android). */
+export function setAccessibilityFocus(ref: { current: TextInput | null } | TextInput | null): void {
+  const node = resolveNode(ref);
+  if (!node) return;
+  const handle = findNodeHandle(node);
+  if (handle != null) {
+    AccessibilityInfo.setAccessibilityFocus?.(handle);
+  }
+}

package/src/intelligence/index.ts

@@ -0,0 +1,12 @@
+export {
+  focusFirstError,
+  announceForAccessibility,
+  buildValidationAnnouncement,
+  setAccessibilityFocus,
+} from './formAccessibility';
+export type { FieldRefMap } from './formAccessibility';
+export type {
+  FieldFrictionStats,
+  FormHealthReport,
+  FormIntelligenceOptions,
+} from './types';

package/src/intelligence/types.ts

@@ -0,0 +1,34 @@
+export interface FieldFrictionStats {
+  focusCount: number;
+  /** Cumulative milliseconds the field was focused. */
+  totalFocusMs: number;
+  errorCount: number;
+  changeCount: number;
+  blurCount: number;
+  lastFocusedAt?: number;
+  /** Running focus session start (ms since epoch); cleared on blur. */
+  focusStartedAt?: number;
+}
+
+export interface FormHealthReport {
+  /** Wall-clock ms from first interaction to this report. */
+  sessionMs: number;
+  submitAttempts: number;
+  successfulSubmits: number;
+  fields: Record<string, FieldFrictionStats>;
+  /**
+   * Fields sorted by estimated friction (errors × 3 + focusCount + changeCount / 10).
+   * Useful for product analytics / debugging onboarding drop-off.
+   */
+  mostFriction: Array<{ field: string; score: number }>;
+  generatedAt: number;
+}
+
+export interface FormIntelligenceOptions {
+  /** Called whenever a new report is produced (submit attempt, or `flush()`). */
+  onReport?: (report: FormHealthReport) => void;
+  /** When true (default), failed submit focuses & announces the first invalid field. */
+  focusFirstError?: boolean;
+  /** Announce errors via `AccessibilityInfo.announceForAccessibility`. Default: true. */
+  announceErrors?: boolean;
+}

package/src/motion/index.ts

@@ -0,0 +1,3 @@
+export { useReducedMotion } from './useReducedMotion';
+export { useFieldMotion } from './useFieldMotion';
+export type { UseFieldMotionOptions, UseFieldMotionResult } from './useFieldMotion';

package/src/motion/useFieldMotion.ts

@@ -0,0 +1,120 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+import { useReducedMotion } from './useReducedMotion';
+
+export interface UseFieldMotionOptions {
+  /** Master switch. Default: true. */
+  enabled?: boolean;
+  isFocused: boolean;
+  hasError: boolean;
+  isSuccess?: boolean;
+  /** Base duration from theme. */
+  duration?: number;
+}
+
+export interface UseFieldMotionResult {
+  /** Apply to the field chrome (input container). */
+  containerStyle: {
+    transform: Array<{ translateX: Animated.AnimatedInterpolation<string | number> }>;
+  };
+  /** Soft focus glow overlay opacity (0–1). */
+  glowOpacity: Animated.Value;
+  /** Footer message fade. */
+  messageOpacity: Animated.Value;
+  /** Success check scale pop. */
+  successScale: Animated.Value;
+  reducedMotion: boolean;
+}
+
+/**
+ * Field micro-interactions: error shake, focus glow, message cross-fade, success pop.
+ * Uses RN Animated only (no Reanimated) and respects Reduce Motion.
+ */
+export function useFieldMotion({
+  enabled = true,
+  isFocused,
+  hasError,
+  isSuccess,
+  duration = 180,
+}: UseFieldMotionOptions): UseFieldMotionResult {
+  const reducedMotion = useReducedMotion();
+  const active = enabled && !reducedMotion;
+
+  const shake = useRef(new Animated.Value(0)).current;
+  const glowOpacity = useRef(new Animated.Value(0)).current;
+  const messageOpacity = useRef(new Animated.Value(1)).current;
+  const successScale = useRef(new Animated.Value(1)).current;
+  const prevError = useRef(hasError);
+
+  // Focus glow
+  useEffect(() => {
+    if (!active) {
+      glowOpacity.setValue(isFocused ? 0.35 : 0);
+      return;
+    }
+    Animated.timing(glowOpacity, {
+      toValue: isFocused ? 1 : 0,
+      duration,
+      easing: Easing.out(Easing.cubic),
+      useNativeDriver: true,
+    }).start();
+  }, [active, isFocused, glowOpacity, duration]);
+
+  // Error shake when error turns on
+  useEffect(() => {
+    const justErrored = hasError && !prevError.current;
+    prevError.current = hasError;
+    if (!justErrored) return;
+
+    if (!active) return;
+
+    shake.setValue(0);
+    Animated.sequence([
+      Animated.timing(shake, { toValue: 1, duration: 40, useNativeDriver: true }),
+      Animated.timing(shake, { toValue: -1, duration: 40, useNativeDriver: true }),
+      Animated.timing(shake, { toValue: 1, duration: 40, useNativeDriver: true }),
+      Animated.timing(shake, { toValue: -1, duration: 40, useNativeDriver: true }),
+      Animated.timing(shake, { toValue: 0, duration: 40, useNativeDriver: true }),
+    ]).start();
+
+    messageOpacity.setValue(0);
+    Animated.timing(messageOpacity, {
+      toValue: 1,
+      duration: duration + 40,
+      easing: Easing.out(Easing.cubic),
+      useNativeDriver: true,
+    }).start();
+  }, [hasError, active, shake, messageOpacity, duration]);
+
+  // Success pop
+  useEffect(() => {
+    if (!isSuccess) {
+      successScale.setValue(1);
+      return;
+    }
+    if (!active) return;
+    successScale.setValue(0.6);
+    Animated.spring(successScale, {
+      toValue: 1,
+      friction: 5,
+      tension: 140,
+      useNativeDriver: true,
+    }).start();
+  }, [isSuccess, active, successScale]);
+
+  const translateX = shake.interpolate({
+    inputRange: [-1, 0, 1],
+    outputRange: [-6, 0, 6],
+  });
+
+  return useMemo(
+    () => ({
+      containerStyle: { transform: [{ translateX }] },
+      glowOpacity,
+      messageOpacity,
+      successScale,
+      reducedMotion,
+    }),
+    [translateX, glowOpacity, messageOpacity, successScale, reducedMotion],
+  );
+}

package/src/motion/useReducedMotion.ts

@@ -0,0 +1,31 @@
+import { useEffect, useState } from 'react';
+import { AccessibilityInfo } from 'react-native';
+
+/**
+ * Tracks the OS “Reduce Motion” preference so FieldFlow can skip decorative animation.
+ */
+export function useReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(false);
+
+  useEffect(() => {
+    let mounted = true;
+    AccessibilityInfo.isReduceMotionEnabled?.()
+      .then(value => {
+        if (mounted) setReduced(Boolean(value));
+      })
+      .catch(() => {
+        /* older RN */
+      });
+
+    const sub = AccessibilityInfo.addEventListener?.('reduceMotionChanged', setReduced);
+    return () => {
+      mounted = false;
+      // RN versions differ: subscription may be `{ remove }` or a legacy remover fn
+      if (sub && typeof (sub as { remove?: () => void }).remove === 'function') {
+        (sub as { remove: () => void }).remove();
+      }
+    };
+  }, []);
+
+  return reduced;
+}

package/src/theme/index.ts

@@ -1,3 +1,5 @@
 export { defaultTheme, darkTheme } from './defaultTheme';
 export { FieldFlowThemeProvider, useFieldFlowTheme, mergeDeep } from './ThemeProvider';
 export type { FieldFlowThemeProviderProps } from './ThemeProvider';
+export { themePresets, getThemePreset } from './presets';
+export type { FieldFlowThemePresetName } from './presets';

package/src/theme/presets.ts

@@ -0,0 +1,120 @@
+import type { DeepPartial, FieldFlowTheme } from '../types';
+import { defaultTheme, darkTheme } from './defaultTheme';
+
+/**
+ * Curated one-liner themes for demos and brand starts.
+ * Pass into `FieldFlowThemeProvider theme={themePresets.soft}`.
+ */
+export const themePresets = {
+  /** Default FieldFlow blue. */
+  default: defaultTheme as DeepPartial<FieldFlowTheme>,
+  /** Bundled dark palette. */
+  dark: darkTheme as DeepPartial<FieldFlowTheme>,
+  /** Soft rounded surfaces, indigo accent. */
+  soft: {
+    colors: {
+      background: '#F8FAFC',
+      backgroundDisabled: '#EEF2F7',
+      border: '#E2E8F0',
+      borderFocused: '#6366F1',
+      borderError: '#F43F5E',
+      borderSuccess: '#10B981',
+      text: '#0F172A',
+      placeholder: '#94A3B8',
+      label: '#475569',
+      labelFocused: '#6366F1',
+      error: '#F43F5E',
+      success: '#10B981',
+      icon: '#64748B',
+      iconFocused: '#6366F1',
+    },
+    spacing: { borderRadius: 16, paddingHorizontal: 16, paddingVertical: 14 },
+    typography: { fontSize: 16, labelFontSize: 13, helperFontSize: 12 },
+  } satisfies DeepPartial<FieldFlowTheme>,
+  /** High-contrast ink on white — docs / legal forms. */
+  contrast: {
+    colors: {
+      background: '#FFFFFF',
+      backgroundDisabled: '#F3F4F6',
+      border: '#111827',
+      borderFocused: '#111827',
+      borderError: '#B91C1C',
+      borderSuccess: '#047857',
+      text: '#111827',
+      placeholder: '#6B7280',
+      label: '#111827',
+      labelFocused: '#111827',
+      error: '#B91C1C',
+      success: '#047857',
+      icon: '#374151',
+      iconFocused: '#111827',
+    },
+    spacing: { borderRadius: 4, borderWidth: 1.5, borderWidthFocused: 2 },
+  } satisfies DeepPartial<FieldFlowTheme>,
+  /** Warm coral accent, cream surfaces. */
+  warm: {
+    colors: {
+      background: '#FFFBF7',
+      backgroundDisabled: '#F5EDE4',
+      border: '#E8D5C4',
+      borderFocused: '#E11D48',
+      borderError: '#DC2626',
+      borderSuccess: '#059669',
+      text: '#1C1917',
+      placeholder: '#A8A29E',
+      label: '#57534E',
+      labelFocused: '#E11D48',
+      error: '#DC2626',
+      success: '#059669',
+      icon: '#78716C',
+      iconFocused: '#E11D48',
+    },
+    spacing: { borderRadius: 12 },
+  } satisfies DeepPartial<FieldFlowTheme>,
+  /** Cool teal — fintech / health. */
+  teal: {
+    colors: {
+      background: '#FFFFFF',
+      backgroundDisabled: '#F0FDFA',
+      border: '#CCFBF1',
+      borderFocused: '#0D9488',
+      borderError: '#E11D48',
+      borderSuccess: '#059669',
+      text: '#134E4A',
+      placeholder: '#5EEAD4',
+      label: '#0F766E',
+      labelFocused: '#0D9488',
+      error: '#E11D48',
+      success: '#059669',
+      icon: '#14B8A6',
+      iconFocused: '#0D9488',
+    },
+    spacing: { borderRadius: 14, paddingHorizontal: 16 },
+  } satisfies DeepPartial<FieldFlowTheme>,
+  /** Midnight elevated cards. */
+  midnight: {
+    colors: {
+      background: '#0B1220',
+      backgroundDisabled: '#111827',
+      border: '#1F2937',
+      borderFocused: '#818CF8',
+      borderError: '#FB7185',
+      borderSuccess: '#34D399',
+      text: '#F9FAFB',
+      placeholder: '#6B7280',
+      label: '#9CA3AF',
+      labelFocused: '#A5B4FC',
+      error: '#FB7185',
+      success: '#34D399',
+      icon: '#9CA3AF',
+      iconFocused: '#A5B4FC',
+    },
+    spacing: { borderRadius: 14 },
+  } satisfies DeepPartial<FieldFlowTheme>,
+} as const;
+
+export type FieldFlowThemePresetName = keyof typeof themePresets;
+
+export function getThemePreset(name: FieldFlowThemePresetName): DeepPartial<FieldFlowTheme> {
+  return themePresets[name];
+}

package/src/utils/affordance.ts

@@ -0,0 +1,138 @@
+export type FieldFlowAffordanceKind = 'email' | 'phone' | 'currency' | 'custom';
+
+export interface FieldFlowAffordanceChip {
+  /** Visible chip label, e.g. "@gmail.com" or "+1". */
+  label: string;
+  /** Value applied when the chip is pressed. Defaults to `label`. */
+  value?: string;
+  /** Optional accessibility label. */
+  accessibilityLabel?: string;
+}
+
+/** Popular consumer email domains for quick completion. */
+export const DEFAULT_EMAIL_DOMAINS: string[] = [
+  'gmail.com',
+  'outlook.com',
+  'hotmail.com',
+  'yahoo.com',
+  'icloud.com',
+  'proton.me',
+  'aol.com',
+  'mail.com',
+];
+
+/** Common dial-code chips (label shown to the user). */
+export const DEFAULT_PHONE_DIAL_CODES: FieldFlowAffordanceChip[] = [
+  { label: '+1', accessibilityLabel: 'United States / Canada +1' },
+  { label: '+44', accessibilityLabel: 'United Kingdom +44' },
+  { label: '+92', accessibilityLabel: 'Pakistan +92' },
+  { label: '+91', accessibilityLabel: 'India +91' },
+  { label: '+61', accessibilityLabel: 'Australia +61' },
+  { label: '+49', accessibilityLabel: 'Germany +49' },
+  { label: '+971', accessibilityLabel: 'UAE +971' },
+  { label: '+966', accessibilityLabel: 'Saudi Arabia +966' },
+];
+
+/** Currency symbol chips. */
+export const DEFAULT_CURRENCY_SYMBOLS: FieldFlowAffordanceChip[] = [
+  { label: '$', value: '$', accessibilityLabel: 'US Dollar' },
+  { label: '€', value: '€', accessibilityLabel: 'Euro' },
+  { label: '£', value: '£', accessibilityLabel: 'British Pound' },
+  { label: '₹', value: '₹', accessibilityLabel: 'Indian Rupee' },
+  { label: 'Rs', value: 'Rs ', accessibilityLabel: 'Rupee' },
+  { label: 'AED', value: 'AED ', accessibilityLabel: 'UAE Dirham' },
+];
+
+export function emailDomainsToChips(domains: string[]): FieldFlowAffordanceChip[] {
+  return domains.map(domain => ({
+    label: `@${domain}`,
+    value: domain,
+    accessibilityLabel: `Complete with ${domain}`,
+  }));
+}
+
+/**
+ * Apply an email-domain suggestion to the current value.
+ * - `jane` + `gmail.com` → `jane@gmail.com`
+ * - `jane@hot` + `gmail.com` → `jane@gmail.com`
+ * - `jane@gmail.com` + `outlook.com` → `jane@outlook.com`
+ */
+export function applyEmailDomainSuggestion(current: string, domain: string): string {
+  const cleanedDomain = domain.replace(/^@/, '');
+  const at = current.indexOf('@');
+  if (at === -1) {
+    const local = current.trim();
+    return local ? `${local}@${cleanedDomain}` : `@${cleanedDomain}`;
+  }
+  return `${current.slice(0, at)}@${cleanedDomain}`;
+}
+
+/**
+ * Apply a dial-code chip. Replaces an existing leading `+digits` prefix when present.
+ */
+export function applyPhoneDialSuggestion(current: string, dialCode: string): string {
+  const code = dialCode.startsWith('+') ? dialCode : `+${dialCode}`;
+  const rest = current.replace(/^\s*\+?\d{0,4}\s*/, '');
+  return rest ? `${code} ${rest.trimStart()}` : code;
+}
+
+/**
+ * Ensure the value starts with the currency symbol (does not duplicate if already present).
+ */
+export function applyCurrencySymbolSuggestion(current: string, symbol: string): string {
+  const trimmed = current.trimStart();
+  if (trimmed.startsWith(symbol.trim())) return current;
+  const digits = trimmed.replace(/^[^\d.-]+/, '');
+  return `${symbol}${digits}`;
+}
+
+export function resolveAffordanceChips(
+  kind: FieldFlowAffordanceKind,
+  custom?: FieldFlowAffordanceChip[] | string[],
+): FieldFlowAffordanceChip[] {
+  if (custom && custom.length > 0) {
+    return custom.map(item =>
+      typeof item === 'string'
+        ? { label: item.startsWith('@') || item.startsWith('+') ? item : item, value: item }
+        : item,
+    );
+  }
+  switch (kind) {
+    case 'email':
+      return emailDomainsToChips(DEFAULT_EMAIL_DOMAINS);
+    case 'phone':
+      return DEFAULT_PHONE_DIAL_CODES;
+    case 'currency':
+      return DEFAULT_CURRENCY_SYMBOLS;
+    default:
+      return [];
+  }
+}
+
+export function applyAffordanceSuggestion(
+  kind: FieldFlowAffordanceKind,
+  current: string,
+  chip: FieldFlowAffordanceChip,
+): string {
+  const value = chip.value ?? chip.label;
+  switch (kind) {
+    case 'email':
+      return applyEmailDomainSuggestion(current, value);
+    case 'phone':
+      return applyPhoneDialSuggestion(current, value);
+    case 'currency':
+      return applyCurrencySymbolSuggestion(current, value);
+    default:
+      return value;
+  }
+}
+
+/** Infer affordance kind from FieldFlow input `type`. */
+export function affordanceKindFromFieldType(
+  type?: string,
+): FieldFlowAffordanceKind | undefined {
+  if (type === 'email') return 'email';
+  if (type === 'phone') return 'phone';
+  if (type === 'decimal' || type === 'number') return 'currency';
+  return undefined;
+}

package/src/utils/passwordStrength.ts

@@ -0,0 +1,109 @@
+export type PasswordStrengthLevel = 'empty' | 'weak' | 'fair' | 'good' | 'strong';
+
+export interface PasswordStrengthRule {
+  id: string;
+  label: string;
+  test: (password: string) => boolean;
+}
+
+export interface PasswordStrengthResult {
+  score: number;
+  /** 0–4 mapped level (empty when score is 0 and password is empty). */
+  level: PasswordStrengthLevel;
+  /** Fraction 0–1 for progress bars. */
+  progress: number;
+  passed: PasswordStrengthRule[];
+  failed: PasswordStrengthRule[];
+  /** Short human label, e.g. "Strong". */
+  label: string;
+}
+
+export const DEFAULT_PASSWORD_RULES: PasswordStrengthRule[] = [
+  {
+    id: 'length',
+    label: 'At least 8 characters',
+    test: p => p.length >= 8,
+  },
+  {
+    id: 'lowercase',
+    label: 'A lowercase letter',
+    test: p => /[a-z]/.test(p),
+  },
+  {
+    id: 'uppercase',
+    label: 'An uppercase letter',
+    test: p => /[A-Z]/.test(p),
+  },
+  {
+    id: 'number',
+    label: 'A number',
+    test: p => /\d/.test(p),
+  },
+  {
+    id: 'symbol',
+    label: 'A symbol',
+    test: p => /[^A-Za-z0-9]/.test(p),
+  },
+];
+
+const LEVEL_LABELS: Record<PasswordStrengthLevel, string> = {
+  empty: '',
+  weak: 'Weak',
+  fair: 'Fair',
+  good: 'Good',
+  strong: 'Strong',
+};
+
+/**
+ * Score a password against declarative rules (default NIST-ish checklist).
+ * Pure function — safe to unit test and reuse outside React.
+ */
+export function evaluatePasswordStrength(
+  password: string,
+  rules: PasswordStrengthRule[] = DEFAULT_PASSWORD_RULES,
+): PasswordStrengthResult {
+  if (!password) {
+    return {
+      score: 0,
+      level: 'empty',
+      progress: 0,
+      passed: [],
+      failed: [...rules],
+      label: LEVEL_LABELS.empty,
+    };
+  }
+
+  const passed: PasswordStrengthRule[] = [];
+  const failed: PasswordStrengthRule[] = [];
+  for (const rule of rules) {
+    if (rule.test(password)) passed.push(rule);
+    else failed.push(rule);
+  }
+
+  const score = passed.length;
+  const max = Math.max(rules.length, 1);
+  const ratio = score / max;
+
+  let level: PasswordStrengthLevel;
+  if (ratio < 0.4) level = 'weak';
+  else if (ratio < 0.6) level = 'fair';
+  else if (ratio < 0.85) level = 'good';
+  else level = 'strong';
+
+  return {
+    score,
+    level,
+    progress: ratio,
+    passed,
+    failed,
+    label: LEVEL_LABELS[level],
+  };
+}
+
+/** Suggested bar colors for each level (consumers can override). */
+export const PASSWORD_STRENGTH_COLORS: Record<Exclude<PasswordStrengthLevel, 'empty'>, string> = {
+  weak: '#EF4444',
+  fair: '#F59E0B',
+  good: '#3B82F6',
+  strong: '#22C55E',
+};