rn-inputforge 0.3.1 → 0.5.0

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

@@ -0,0 +1,137 @@
+export type FieldFlowMaskType = 'phone' | 'card' | 'currency' | 'date' | 'custom';
+
+export interface MaskResult {
+  /** Display value shown in the input. */
+  formatted: string;
+  /** Digits / raw value without mask characters (currency keeps decimal point). */
+  raw: string;
+}
+
+export interface ApplyMaskOptions {
+  /** Currency symbol prefix, e.g. "$" or "Rs ". Default: "$". */
+  currencySymbol?: string;
+  /** Max decimal places for currency. Default: 2. */
+  currencyDecimals?: number;
+  /** Custom mask pattern using `#` for digits. E.g. `(###) ###-####`. */
+  pattern?: string;
+}
+
+/** Strip everything except digits. */
+export function digitsOnly(value: string): string {
+  return value.replace(/\D/g, '');
+}
+
+/**
+ * Apply a digit pattern where `#` is a digit slot and any other char is literal.
+ * Extra digits beyond the pattern are ignored.
+ */
+export function applyPattern(rawDigits: string, pattern: string): MaskResult {
+  let di = 0;
+  let formatted = '';
+  for (let i = 0; i < pattern.length && di < rawDigits.length; i++) {
+    const ch = pattern[i];
+    if (ch === '#') {
+      formatted += rawDigits[di++];
+    } else {
+      formatted += ch;
+    }
+  }
+  return { formatted, raw: rawDigits.slice(0, di) };
+}
+
+export function applyPhoneMask(value: string): MaskResult {
+  const digits = digitsOnly(value).slice(0, 15);
+  // US-style when 10 digits or less; otherwise keep a loose international grouping
+  if (digits.length <= 10) {
+    return applyPattern(digits, '(###) ###-####');
+  }
+  // +X (XXX) XXX-XXXX… style for longer numbers
+  const country = digits.slice(0, digits.length - 10);
+  const rest = applyPattern(digits.slice(-10), '(###) ###-####').formatted;
+  return { formatted: `+${country} ${rest}`, raw: digits };
+}
+
+export function applyCardMask(value: string): MaskResult {
+  const digits = digitsOnly(value).slice(0, 19);
+  const groups = digits.match(/.{1,4}/g) ?? [];
+  return { formatted: groups.join(' '), raw: digits };
+}
+
+export function applyDateMask(value: string): MaskResult {
+  // MM/DD/YYYY
+  return applyPattern(digitsOnly(value).slice(0, 8), '##/##/####');
+}
+
+export function applyCurrencyMask(
+  value: string,
+  symbol = '$',
+  decimals = 2,
+): MaskResult {
+  // Keep only digits and at most one decimal point
+  let cleaned = value.replace(/[^0-9.]/g, '');
+  const firstDot = cleaned.indexOf('.');
+  if (firstDot !== -1) {
+    cleaned =
+      cleaned.slice(0, firstDot + 1) + cleaned.slice(firstDot + 1).replace(/\./g, '');
+    const [intPart, frac = ''] = cleaned.split('.');
+    cleaned = `${intPart}.${frac.slice(0, decimals)}`;
+  }
+
+  if (!cleaned || cleaned === '.') {
+    return { formatted: '', raw: '' };
+  }
+
+  const [intRaw, fracRaw] = cleaned.split('.');
+  const intFormatted = (intRaw || '0').replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+  const formatted =
+    fracRaw !== undefined ? `${symbol}${intFormatted}.${fracRaw}` : `${symbol}${intFormatted}`;
+
+  return { formatted, raw: cleaned };
+}
+
+/**
+ * Format a value with a built-in or custom mask.
+ * Pass the previous formatted value's raw length context via the incoming `value`
+ * (the function always re-derives from the full string the user typed).
+ */
+export function applyMask(
+  value: string,
+  type: FieldFlowMaskType,
+  options: ApplyMaskOptions = {},
+): MaskResult {
+  switch (type) {
+    case 'phone':
+      return applyPhoneMask(value);
+    case 'card':
+      return applyCardMask(value);
+    case 'date':
+      return applyDateMask(value);
+    case 'currency':
+      return applyCurrencyMask(value, options.currencySymbol ?? '$', options.currencyDecimals ?? 2);
+    case 'custom':
+      if (!options.pattern) {
+        return { formatted: value, raw: value };
+      }
+      return applyPattern(digitsOnly(value), options.pattern);
+    default:
+      return { formatted: value, raw: value };
+  }
+}
+
+/** Convenience: return only the formatted display string. */
+export function formatMasked(
+  value: string,
+  type: FieldFlowMaskType,
+  options?: ApplyMaskOptions,
+): string {
+  return applyMask(value, type, options).formatted;
+}
+
+/** Convenience: return only the raw (unmasked) value. */
+export function unmask(
+  value: string,
+  type: FieldFlowMaskType,
+  options?: ApplyMaskOptions,
+): string {
+  return applyMask(value, type, options).raw;
+}

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

package/src/utils/phoneCountries.ts

@@ -0,0 +1,44 @@
+export interface FieldFlowCountryDial {
+  /** ISO 3166-1 alpha-2 */
+  code: string;
+  name: string;
+  dial: string;
+  flag?: string;
+}
+
+/** Common dial codes for `FieldFlowPhone`. Extend via `countries` prop. */
+export const DEFAULT_COUNTRY_DIALS: FieldFlowCountryDial[] = [
+  { code: 'US', name: 'United States', dial: '+1', flag: '🇺🇸' },
+  { code: 'GB', name: 'United Kingdom', dial: '+44', flag: '🇬🇧' },
+  { code: 'CA', name: 'Canada', dial: '+1', flag: '🇨🇦' },
+  { code: 'AU', name: 'Australia', dial: '+61', flag: '🇦🇺' },
+  { code: 'DE', name: 'Germany', dial: '+49', flag: '🇩🇪' },
+  { code: 'FR', name: 'France', dial: '+33', flag: '🇫🇷' },
+  { code: 'IN', name: 'India', dial: '+91', flag: '🇮🇳' },
+  { code: 'PK', name: 'Pakistan', dial: '+92', flag: '🇵🇰' },
+  { code: 'AE', name: 'United Arab Emirates', dial: '+971', flag: '🇦🇪' },
+  { code: 'SA', name: 'Saudi Arabia', dial: '+966', flag: '🇸🇦' },
+  { code: 'BR', name: 'Brazil', dial: '+55', flag: '🇧🇷' },
+  { code: 'MX', name: 'Mexico', dial: '+52', flag: '🇲🇽' },
+  { code: 'NG', name: 'Nigeria', dial: '+234', flag: '🇳🇬' },
+  { code: 'ZA', name: 'South Africa', dial: '+27', flag: '🇿🇦' },
+  { code: 'JP', name: 'Japan', dial: '+81', flag: '🇯🇵' },
+  { code: 'KR', name: 'South Korea', dial: '+82', flag: '🇰🇷' },
+  { code: 'CN', name: 'China', dial: '+86', flag: '🇨🇳' },
+  { code: 'SG', name: 'Singapore', dial: '+65', flag: '🇸🇬' },
+  { code: 'TR', name: 'Turkey', dial: '+90', flag: '🇹🇷' },
+  { code: 'ES', name: 'Spain', dial: '+34', flag: '🇪🇸' },
+];
+
+export function findCountryByCode(
+  code: string,
+  list: FieldFlowCountryDial[] = DEFAULT_COUNTRY_DIALS,
+): FieldFlowCountryDial | undefined {
+  return list.find(c => c.code === code);
+}
+
+export function composeE164(dial: string, national: string): string {
+  const digits = national.replace(/\D/g, '');
+  const dialDigits = dial.replace(/\D/g, '');
+  return `+${dialDigits}${digits}`;
+}

package/src/validation/index.ts

@@ -13,3 +13,10 @@ export {
 } from './validators';
 export { useValidation } from './useValidation';
 export type { UseValidationResult } from './useValidation';
+export {
+  zodToFormErrors,
+  zodFormValidate,
+  createZodSubmitGuard,
+  fieldRulesFromZodString,
+} from './zodAdapter';
+export type { ZodSchemaLike, ZodIssueLike, ZodErrorLike } from './zodAdapter';

package/src/validation/validators.ts

@@ -1,4 +1,8 @@
 import type { FieldFlowRules, ValidationResult, Validator } from '../types';
+import {
+  getValidationMessages,
+  type FieldFlowValidationMessages,
+} from '../i18n/messages';
 
 const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 const NUMBER_REGEX = /^-?\d+(\.\d+)?$/;
@@ -50,35 +54,41 @@ export const patternValidator =
 /**
  * Turns a declarative `FieldFlowRules` object into an ordered list of validators
  * and runs them against a value, stopping at (and returning) the first failure.
+ * Pass `messages` (or use `locale` via `useFieldFlowForm`) for localized defaults.
  */
-export function runRules(value: string, rules?: FieldFlowRules): ValidationResult {
+export function runRules(
+  value: string,
+  rules?: FieldFlowRules,
+  messages?: FieldFlowValidationMessages,
+): ValidationResult {
   if (!rules) return { valid: true };
 
+  const msg = messages ?? getValidationMessages('en');
   const validators: Validator[] = [];
 
   if (rules.required) {
-    const message = typeof rules.required === 'string' ? rules.required : undefined;
+    const message = typeof rules.required === 'string' ? rules.required : msg.required;
     validators.push(requiredValidator(message));
   }
   if (rules.email) {
-    const message = typeof rules.email === 'string' ? rules.email : undefined;
+    const message = typeof rules.email === 'string' ? rules.email : msg.email;
     validators.push(emailValidator(message));
   }
   if (rules.number) {
-    const message = typeof rules.number === 'string' ? rules.number : undefined;
+    const message = typeof rules.number === 'string' ? rules.number : msg.number;
     validators.push(numberValidator(message));
   }
   if (rules.minLength !== undefined) {
     const cfg = typeof rules.minLength === 'number' ? { value: rules.minLength } : rules.minLength;
-    validators.push(minLengthValidator(cfg.value, cfg.message));
+    validators.push(minLengthValidator(cfg.value, cfg.message ?? msg.minLength(cfg.value)));
   }
   if (rules.maxLength !== undefined) {
     const cfg = typeof rules.maxLength === 'number' ? { value: rules.maxLength } : rules.maxLength;
-    validators.push(maxLengthValidator(cfg.value, cfg.message));
+    validators.push(maxLengthValidator(cfg.value, cfg.message ?? msg.maxLength(cfg.value)));
   }
   if (rules.pattern) {
     const cfg = rules.pattern instanceof RegExp ? { value: rules.pattern } : rules.pattern;
-    validators.push(patternValidator(cfg.value, cfg.message));
+    validators.push(patternValidator(cfg.value, cfg.message ?? msg.pattern));
   }
   if (rules.custom) {
     const customs = Array.isArray(rules.custom) ? rules.custom : [rules.custom];

package/src/validation/zodAdapter.ts

@@ -0,0 +1,103 @@
+import type { FieldFlowRules } from '../types';
+
+/**
+ * Minimal structural types so consumers can pass a Zod schema without
+ * rn-inputforge taking a hard dependency on `zod`.
+ */
+export interface ZodIssueLike {
+  path: (string | number)[];
+  message: string;
+}
+
+export interface ZodErrorLike {
+  issues: ZodIssueLike[];
+}
+
+export interface ZodSchemaLike<T = unknown> {
+  safeParse: (data: unknown) => { success: true; data: T } | { success: false; error: ZodErrorLike };
+}
+
+/**
+ * Convert a Zod schema parse failure into FieldFlow form errors
+ * (first message per top-level field).
+ */
+export function zodToFormErrors<T extends Record<string, string>>(
+  schema: ZodSchemaLike<T>,
+  values: T,
+): Partial<Record<keyof T, string>> {
+  const result = schema.safeParse(values);
+  if (result.success) return {};
+
+  const errors: Partial<Record<keyof T, string>> = {};
+  for (const issue of result.error.issues) {
+    const key = issue.path[0];
+    if (typeof key === 'string' && errors[key as keyof T] === undefined) {
+      errors[key as keyof T] = issue.message;
+    }
+  }
+  return errors;
+}
+
+/**
+ * Drop into `useFieldFlowForm({ formValidate: zodFormValidate(schema) })`.
+ */
+export function zodFormValidate<T extends Record<string, string>>(schema: ZodSchemaLike<T>) {
+  return (values: T) => zodToFormErrors(schema, values);
+}
+
+/**
+ * Wrap an `onSubmit` so it only runs when Zod passes.
+ * Useful if you keep FieldFlow rules for UX and Zod as the final gate.
+ */
+export function createZodSubmitGuard<T extends Record<string, string>>(
+  schema: ZodSchemaLike<T>,
+  onValid: (values: T) => void | Promise<void>,
+  onInvalid?: (errors: Partial<Record<keyof T, string>>) => void,
+) {
+  return async (values: T) => {
+    const errors = zodToFormErrors(schema, values);
+    if (Object.keys(errors).length > 0) {
+      onInvalid?.(errors);
+      return;
+    }
+    await onValid(values);
+  };
+}
+
+/**
+ * Best-effort map of a Zod string schema onto declarative `FieldFlowRules`.
+ * Supports required / email / min / max / regex. For refinements and objects,
+ * use `zodFormValidate` instead.
+ */
+export function fieldRulesFromZodString(zodStringSchema: {
+  _def?: {
+    typeName?: string;
+    checks?: Array<{ kind: string; value?: unknown; regex?: RegExp; message?: string }>;
+  };
+  isOptional?: () => boolean;
+}): FieldFlowRules {
+  const rules: FieldFlowRules = {};
+  const def = zodStringSchema._def;
+  if (!def) return rules;
+
+  const optional = typeof zodStringSchema.isOptional === 'function' ? zodStringSchema.isOptional() : false;
+  if (!optional) rules.required = true;
+
+  for (const check of def.checks ?? []) {
+    if (check.kind === 'email') {
+      rules.email = check.message ?? true;
+    } else if (check.kind === 'min' && typeof check.value === 'number') {
+      if (check.value === 1 && !optional) {
+        rules.required = check.message ?? true;
+      } else {
+        rules.minLength = { value: check.value, message: check.message };
+      }
+    } else if (check.kind === 'max' && typeof check.value === 'number') {
+      rules.maxLength = { value: check.value, message: check.message };
+    } else if (check.kind === 'regex' && check.regex) {
+      rules.pattern = { value: check.regex, message: check.message };
+    }
+  }
+
+  return rules;
+}