rn-inputforge 0.3.1 → 0.5.0

package/lib/typescript/utils/masks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"masks.d.ts","sourceRoot":"","sources":["../../../src/utils/masks.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;AAElF,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,sCAAsC;AACtC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAY3E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAUxD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAIvD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAGvD;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,SAAM,EACZ,QAAQ,SAAI,GACX,UAAU,CAqBZ;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,iBAAiB,EACvB,OAAO,GAAE,gBAAqB,GAC7B,UAAU,CAkBZ;AAED,6DAA6D;AAC7D,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,iBAAiB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,CAER;AAED,yDAAyD;AACzD,wBAAgB,MAAM,CACpB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,iBAAiB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,CAER"}

package/lib/typescript/utils/passwordStrength.d.ts

@@ -0,0 +1,26 @@
+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 declare const DEFAULT_PASSWORD_RULES: PasswordStrengthRule[];
+/**
+ * Score a password against declarative rules (default NIST-ish checklist).
+ * Pure function — safe to unit test and reuse outside React.
+ */
+export declare function evaluatePasswordStrength(password: string, rules?: PasswordStrengthRule[]): PasswordStrengthResult;
+/** Suggested bar colors for each level (consumers can override). */
+export declare const PASSWORD_STRENGTH_COLORS: Record<Exclude<PasswordStrengthLevel, 'empty'>, string>;
+//# sourceMappingURL=passwordStrength.d.ts.map

package/lib/typescript/utils/passwordStrength.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passwordStrength.d.ts","sourceRoot":"","sources":["../../../src/utils/passwordStrength.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAElF,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,KAAK,EAAE,qBAAqB,CAAC;IAC7B,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,sBAAsB,EAAE,oBAAoB,EA0BxD,CAAC;AAUF;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,oBAAoB,EAA2B,GACrD,sBAAsB,CAqCxB;AAED,oEAAoE;AACpE,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,OAAO,CAAC,qBAAqB,EAAE,OAAO,CAAC,EAAE,MAAM,CAK5F,CAAC"}

package/lib/typescript/utils/phoneCountries.d.ts

@@ -0,0 +1,12 @@
+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 declare const DEFAULT_COUNTRY_DIALS: FieldFlowCountryDial[];
+export declare function findCountryByCode(code: string, list?: FieldFlowCountryDial[]): FieldFlowCountryDial | undefined;
+export declare function composeE164(dial: string, national: string): string;
+//# sourceMappingURL=phoneCountries.d.ts.map

package/lib/typescript/utils/phoneCountries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phoneCountries.d.ts","sourceRoot":"","sources":["../../../src/utils/phoneCountries.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACnC,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,EAAE,oBAAoB,EAqBvD,CAAC;AAEF,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,oBAAoB,EAA0B,GACnD,oBAAoB,GAAG,SAAS,CAElC;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIlE"}

package/lib/typescript/validation/index.d.ts

@@ -1,4 +1,6 @@
 export { isValidEmail, isValidNumber, isValidPhone, requiredValidator, emailValidator, numberValidator, phoneValidator, minLengthValidator, maxLengthValidator, patternValidator, runRules, } 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';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/validation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/validation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,QAAQ,GACT,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/validation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,QAAQ,GACT,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EACL,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/lib/typescript/validation/validators.d.ts

@@ -1,4 +1,5 @@
 import type { FieldFlowRules, ValidationResult, Validator } from '../types';
+import { type FieldFlowValidationMessages } from '../i18n/messages';
 export declare const isValidEmail: (value: string) => boolean;
 export declare const isValidNumber: (value: string) => boolean;
 export declare const isValidPhone: (value: string) => boolean;
@@ -12,6 +13,7 @@ export declare const patternValidator: (pattern: RegExp, message?: string) => Va
 /**
  * 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 declare function runRules(value: string, rules?: FieldFlowRules): ValidationResult;
+export declare function runRules(value: string, rules?: FieldFlowRules, messages?: FieldFlowValidationMessages): ValidationResult;
 //# sourceMappingURL=validators.d.ts.map

package/lib/typescript/validation/validators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../src/validation/validators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAM5E,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,OAAyC,CAAC;AACvF,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,KAAG,OAA0C,CAAC;AACzF,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,OAAyC,CAAC;AAEvF,eAAO,MAAM,iBAAiB,GAC3B,gBAAkC,KAAG,SAIP,CAAC;AAElC,eAAO,MAAM,cAAc,GACxB,gBAAuC,KAAG,SAE8C,CAAC;AAE5F,eAAO,MAAM,eAAe,GACzB,gBAAgC,KAAG,SAEsD,CAAC;AAE7F,eAAO,MAAM,cAAc,GACxB,gBAAsC,KAAG,SAE+C,CAAC;AAE5F,eAAO,MAAM,kBAAkB,GAC5B,KAAK,MAAM,EAAE,UAAU,MAAM,KAAG,SAI+C,CAAC;AAEnF,eAAO,MAAM,kBAAkB,GAC5B,KAAK,MAAM,EAAE,UAAU,MAAM,KAAG,SAEkF,CAAC;AAEtH,eAAO,MAAM,gBAAgB,GAC1B,SAAS,MAAM,EAAE,gBAA0B,KAAG,SAE0C,CAAC;AAE5F;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,gBAAgB,CAuChF"}
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../src/validation/validators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC5E,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,kBAAkB,CAAC;AAM1B,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,OAAyC,CAAC;AACvF,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,KAAG,OAA0C,CAAC;AACzF,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,OAAyC,CAAC;AAEvF,eAAO,MAAM,iBAAiB,GAC3B,gBAAkC,KAAG,SAIP,CAAC;AAElC,eAAO,MAAM,cAAc,GACxB,gBAAuC,KAAG,SAE8C,CAAC;AAE5F,eAAO,MAAM,eAAe,GACzB,gBAAgC,KAAG,SAEsD,CAAC;AAE7F,eAAO,MAAM,cAAc,GACxB,gBAAsC,KAAG,SAE+C,CAAC;AAE5F,eAAO,MAAM,kBAAkB,GAC5B,KAAK,MAAM,EAAE,UAAU,MAAM,KAAG,SAI+C,CAAC;AAEnF,eAAO,MAAM,kBAAkB,GAC5B,KAAK,MAAM,EAAE,UAAU,MAAM,KAAG,SAEkF,CAAC;AAEtH,eAAO,MAAM,gBAAgB,GAC1B,SAAS,MAAM,EAAE,gBAA0B,KAAG,SAE0C,CAAC;AAE5F;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,cAAc,EACtB,QAAQ,CAAC,EAAE,2BAA2B,GACrC,gBAAgB,CAwClB"}

package/lib/typescript/validation/zodAdapter.d.ts

@@ -0,0 +1,53 @@
+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 declare function zodToFormErrors<T extends Record<string, string>>(schema: ZodSchemaLike<T>, values: T): Partial<Record<keyof T, string>>;
+/**
+ * Drop into `useFieldFlowForm({ formValidate: zodFormValidate(schema) })`.
+ */
+export declare function zodFormValidate<T extends Record<string, string>>(schema: ZodSchemaLike<T>): (values: T) => Partial<Record<keyof T, string>>;
+/**
+ * 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 declare function createZodSubmitGuard<T extends Record<string, string>>(schema: ZodSchemaLike<T>, onValid: (values: T) => void | Promise<void>, onInvalid?: (errors: Partial<Record<keyof T, string>>) => void): (values: T) => Promise<void>;
+/**
+ * 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 declare function fieldRulesFromZodString(zodStringSchema: {
+    _def?: {
+        typeName?: string;
+        checks?: Array<{
+            kind: string;
+            value?: unknown;
+            regex?: RegExp;
+            message?: string;
+        }>;
+    };
+    isOptional?: () => boolean;
+}): FieldFlowRules;
+//# sourceMappingURL=zodAdapter.d.ts.map

package/lib/typescript/validation/zodAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zodAdapter.d.ts","sourceRoot":"","sources":["../../../src/validation/zodAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,YAAY,CAAA;KAAE,CAAC;CACpG;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9D,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,MAAM,EAAE,CAAC,GACR,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAYlC;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,IAChF,QAAQ,CAAC,sCAClB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAC5C,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,IAAI,IAEhD,QAAQ,CAAC,mBAQxB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,eAAe,EAAE;IACvD,IAAI,CAAC,EAAE;QACL,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,OAAO,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACrF,CAAC;IACF,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;CAC5B,GAAG,cAAc,CAyBjB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rn-inputforge",
-  "version": "0.3.1",
-  "description": "A production-ready, highly customizable input field system for React Native (bare CLI) — text/email/number/phone/password/search fields, description fields, chat input, and a single/multi-select dropdown (bottom sheet, popup, or inline), with built-in validation, theming, icons, and keyboard-aware form navigation.",
+  "version": "0.5.0",
+  "description": "A production-ready React Native input/form system (bare CLI & Expo) — fields, OTP, masks, date/time, phone+country, upload, typeahead, rating, slider, stepper, credit card, signature, multi-step wizard, tags, password strength, drafts, motion UI, i18n validation, react-hook-form + Zod adapters. Pure JS/TS, no native modules.",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
   "types": "lib/typescript/index.d.ts",
@@ -23,6 +23,7 @@
     "build": "bob build",
     "prepare": "bob build",
     "typecheck": "tsc --noEmit -p tsconfig.build.json",
+    "test": "jest",
     "lint": "eslint \"src/**/*.{ts,tsx}\"",
     "clean": "rimraf lib"
   },
@@ -33,13 +34,29 @@
     "form",
     "form-builder",
     "chat-input",
+    "otp",
+    "pin",
+    "masked-input",
+    "checkbox",
+    "radio",
+    "switch",
     "dropdown",
     "select",
     "multi-select",
     "bottom-sheet",
     "keyboard-aware",
     "validation",
+    "zod",
+    "form-draft",
+    "conditional-fields",
+    "field-array",
+    "accessibility",
+    "email-autocomplete",
+    "password-strength",
+    "tags-input",
+    "react-hook-form",
     "typescript",
+    "expo",
     "bare-react-native-cli"
   ],
   "author": "Saad Waheed Khan",
@@ -54,17 +71,31 @@
   },
   "peerDependencies": {
     "react": ">=18.0.0",
-    "react-native": ">=0.73.0"
+    "react-native": ">=0.73.0",
+    "react-hook-form": ">=7.0.0",
+    "zod": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-hook-form": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@react-native/eslint-config": "^0.81.0",
+    "@types/jest": "^29.5.14",
     "@types/react": "^19.2.0",
     "eslint": "^9.19.0",
+    "jest": "^29.7.0",
     "prettier": "^3.4.2",
     "react": "19.2.8",
+    "react-hook-form": "^7.54.2",
     "react-native": "0.86.2",
     "react-native-builder-bob": "^0.43.0",
     "rimraf": "^6.0.1",
+    "ts-jest": "^29.2.5",
     "typescript": "^5.7.3"
   },
   "engines": {

package/src/adapters/index.ts

@@ -0,0 +1,9 @@
+export {
+  FieldFlowController,
+  FieldFlowTagsController,
+  mapRhfToFieldFlowProps,
+} from './reactHookForm';
+export type {
+  FieldFlowControllerProps,
+  FieldFlowTagsControllerProps,
+} from './reactHookForm';

package/src/adapters/reactHookForm.tsx

@@ -0,0 +1,152 @@
+import React from 'react';
+import type { TextInput } from 'react-native';
+import {
+  Controller,
+  type Control,
+  type ControllerProps,
+  type FieldPath,
+  type FieldValues,
+  type RegisterOptions,
+} from 'react-hook-form';
+import { FieldFlowInput, type FieldFlowInputProps } from '../components/FieldFlowInput';
+import { FieldFlowTags, type FieldFlowTagsProps } from '../components/FieldFlowTags';
+
+type InputPassthrough = Omit<
+  FieldFlowInputProps,
+  | 'value'
+  | 'defaultValue'
+  | 'onChangeText'
+  | 'onBlur'
+  | 'onFocus'
+  | 'errorText'
+  | 'hasError'
+  | 'rules'
+>;
+
+export interface FieldFlowControllerProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> extends InputPassthrough {
+  control: Control<TFieldValues>;
+  name: TName;
+  /** react-hook-form register/controller rules. */
+  rules?: RegisterOptions<TFieldValues, TName>;
+  defaultValue?: ControllerProps<TFieldValues, TName>['defaultValue'];
+  /** When true, show the field error message from RHF. Default: true. */
+  showError?: boolean;
+}
+
+/**
+ * Drop-in `Controller` wrapper that renders a themed `FieldFlowInput`
+ * wired to react-hook-form. Requires the optional `react-hook-form` peer.
+ *
+ * @example
+ * const { control, handleSubmit } = useForm({ defaultValues: { email: '' } });
+ *
+ * <FieldFlowController
+ *   control={control}
+ *   name="email"
+ *   type="email"
+ *   label="Email"
+ *   rules={{ required: 'Email is required' }}
+ *   suggestions
+ * />
+ */
+export function FieldFlowController<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+>({
+  control,
+  name,
+  rules,
+  defaultValue,
+  showError = true,
+  ...inputProps
+}: FieldFlowControllerProps<TFieldValues, TName>) {
+  return (
+    <Controller
+      control={control}
+      name={name}
+      rules={rules}
+      defaultValue={defaultValue}
+      render={({ field, fieldState }) => (
+        <FieldFlowInput
+          {...inputProps}
+          ref={field.ref as React.Ref<TextInput>}
+          value={field.value == null ? '' : String(field.value)}
+          onChangeText={field.onChange}
+          onBlur={field.onBlur}
+          errorText={showError ? fieldState.error?.message : undefined}
+          hasError={showError ? Boolean(fieldState.error) : undefined}
+        />
+      )}
+    />
+  );
+}
+
+type TagsPassthrough = Omit<FieldFlowTagsProps, 'value' | 'onChange' | 'errorText' | 'hasError'>;
+
+export interface FieldFlowTagsControllerProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> extends TagsPassthrough {
+  control: Control<TFieldValues>;
+  name: TName;
+  rules?: RegisterOptions<TFieldValues, TName>;
+  defaultValue?: ControllerProps<TFieldValues, TName>['defaultValue'];
+  showError?: boolean;
+}
+
+/**
+ * RHF `Controller` for `FieldFlowTags` (string[] values).
+ */
+export function FieldFlowTagsController<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+>({
+  control,
+  name,
+  rules,
+  defaultValue,
+  showError = true,
+  ...tagsProps
+}: FieldFlowTagsControllerProps<TFieldValues, TName>) {
+  return (
+    <Controller
+      control={control}
+      name={name}
+      rules={rules}
+      defaultValue={defaultValue}
+      render={({ field, fieldState }) => (
+        <FieldFlowTags
+          {...tagsProps}
+          value={Array.isArray(field.value) ? field.value : []}
+          onChange={field.onChange}
+          errorText={showError ? fieldState.error?.message : undefined}
+          hasError={showError ? Boolean(fieldState.error) : undefined}
+        />
+      )}
+    />
+  );
+}
+
+/**
+ * Map an RHF `field` + `fieldState` onto common FieldFlow input props.
+ * Useful when you need a custom render or a non-input FieldFlow component.
+ */
+export function mapRhfToFieldFlowProps(args: {
+  value: unknown;
+  onChange: (...event: any[]) => void;
+  onBlur: () => void;
+  errorMessage?: string;
+  showError?: boolean;
+}): Pick<FieldFlowInputProps, 'value' | 'onChangeText' | 'onBlur' | 'errorText' | 'hasError'> {
+  const { value, onChange, onBlur, errorMessage, showError = true } = args;
+  return {
+    value: value == null ? '' : String(value),
+    onChangeText: onChange,
+    onBlur,
+    errorText: showError ? errorMessage : undefined,
+    hasError: showError ? Boolean(errorMessage) : undefined,
+  };
+}

package/src/components/FieldFlowAffordance/FieldFlowAffordance.tsx

@@ -0,0 +1,143 @@
+import React, { useMemo } from 'react';
+import {
+  Pressable,
+  ScrollView,
+  StyleSheet,
+  Text,
+  View,
+  type TextStyle,
+  type ViewStyle,
+} from 'react-native';
+import { useFieldFlowTheme, mergeDeep } from '../../theme/ThemeProvider';
+import { defaultTheme } from '../../theme/defaultTheme';
+import type { DeepPartial, FieldFlowTheme } from '../../types';
+import {
+  applyAffordanceSuggestion,
+  resolveAffordanceChips,
+  type FieldFlowAffordanceChip,
+  type FieldFlowAffordanceKind,
+} from '../../utils/affordance';
+
+export interface FieldFlowAffordanceProps {
+  /** Preset chip set. Ignored when `chips` is provided. */
+  kind?: FieldFlowAffordanceKind;
+  /** Explicit chips (strings or objects). Overrides `kind` defaults when non-empty. */
+  chips?: FieldFlowAffordanceChip[] | string[];
+  /** Current field value — used to compute the next value on chip press. */
+  value?: string;
+  /** Called with the updated field value after a chip is applied. */
+  onSelect: (nextValue: string, chip: FieldFlowAffordanceChip) => void;
+  /** Hide the bar entirely. Useful when the parent field is blurred. Default: false. */
+  hidden?: boolean;
+  /** When true, chips that would leave the value unchanged are still pressable. Default: true. */
+  allowNoop?: boolean;
+  containerStyle?: ViewStyle;
+  chipStyle?: ViewStyle;
+  chipTextStyle?: TextStyle;
+  theme?: DeepPartial<FieldFlowTheme>;
+  testID?: string;
+}
+
+/**
+ * Horizontal suggestion chips shown under (or near) a field — email domains,
+ * phone dial codes, currency symbols, or a fully custom chip list.
+ */
+export function FieldFlowAffordance({
+  kind = 'custom',
+  chips: chipsProp,
+  value = '',
+  onSelect,
+  hidden = false,
+  allowNoop = true,
+  containerStyle,
+  chipStyle,
+  chipTextStyle,
+  theme: themeOverride,
+  testID,
+}: FieldFlowAffordanceProps) {
+  const contextTheme = useFieldFlowTheme();
+  const theme = useMemo(
+    () => (themeOverride ? mergeDeep(contextTheme ?? defaultTheme, themeOverride) : contextTheme ?? defaultTheme),
+    [contextTheme, themeOverride],
+  );
+  const styles = useMemo(() => createStyles(theme), [theme]);
+
+  const chips = useMemo(
+    () => resolveAffordanceChips(kind, chipsProp),
+    [kind, chipsProp],
+  );
+
+  if (hidden || chips.length === 0) return null;
+
+  return (
+    <View style={[styles.wrapper, containerStyle]} testID={testID} accessibilityRole="menu">
+      <ScrollView
+        horizontal
+        showsHorizontalScrollIndicator={false}
+        keyboardShouldPersistTaps="handled"
+        contentContainerStyle={styles.row}
+      >
+        {chips.map((chip, index) => {
+          const next = applyAffordanceSuggestion(kind, value, chip);
+          const disabled = !allowNoop && next === value;
+          return (
+            <Pressable
+              key={`${chip.label}-${index}`}
+              onPress={() => onSelect(next, chip)}
+              disabled={disabled}
+              style={({ pressed }) => [
+                styles.chip,
+                pressed && styles.chipPressed,
+                disabled && styles.chipDisabled,
+                chipStyle,
+              ]}
+              accessibilityRole="button"
+              accessibilityLabel={chip.accessibilityLabel ?? chip.label}
+              accessibilityState={{ disabled }}
+            >
+              <Text style={[styles.chipText, chipTextStyle]} numberOfLines={1}>
+                {chip.label}
+              </Text>
+            </Pressable>
+          );
+        })}
+      </ScrollView>
+    </View>
+  );
+}
+
+function createStyles(theme: FieldFlowTheme) {
+  return StyleSheet.create({
+    wrapper: {
+      marginTop: theme.spacing.gap,
+      marginBottom: theme.spacing.gap / 2,
+    },
+    row: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: theme.spacing.gap,
+      paddingRight: theme.spacing.paddingHorizontal,
+    },
+    chip: {
+      paddingHorizontal: 12,
+      paddingVertical: 7,
+      borderRadius: 999,
+      borderWidth: theme.spacing.borderWidth,
+      borderColor: theme.colors.border,
+      backgroundColor: theme.colors.background,
+    },
+    chipPressed: {
+      borderColor: theme.colors.borderFocused,
+      backgroundColor: theme.colors.backgroundDisabled,
+    },
+    chipDisabled: {
+      opacity: 0.4,
+    },
+    chipText: {
+      fontSize: theme.typography.helperFontSize,
+      color: theme.colors.text,
+      fontWeight: '500',
+      fontFamily: theme.typography.fontFamily,
+    },
+  });
+}

package/src/components/FieldFlowAffordance/index.ts

@@ -0,0 +1,2 @@
+export { FieldFlowAffordance } from './FieldFlowAffordance';
+export type { FieldFlowAffordanceProps } from './FieldFlowAffordance';