rn-inputforge 0.3.1 → 0.5.0

package/README.md

@@ -1,8 +1,107 @@
 # rn-inputforge
 
-A production-ready, highly customizable input field system for **bare React Native CLI** apps — text, email, number, phone, password, search, description, and chat inputs, plus a fully customizable single/multi-select dropdown (bottom sheet, popup, or inline), with built-in validation, theming, icons, and keyboard-aware form navigation. Pure JS/TS, no native modules, so there's nothing to link.
+A production-ready input & form system for **React Native** (bare CLI **and Expo**). Pure JS/TS — no native modules, works with **npm** or **yarn**.
 
-Works identically whether your project uses **npm** or **yarn**.
+One package for fields, validation, theming, motion, drafts, and form UX — so you don’t bolt together five libraries for a signup screen.
+
+---
+
+## What's included
+
+Everything ships from `rn-inputforge`. Use this map to find the right export.
+
+### Fields & controls
+
+| You need… | Use |
+| --------- | --- |
+| Text / email / phone / password / search / number | [`FieldFlowInput`](#field-types) |
+| Phone + country dial code | [`FieldFlowPhone`](#phone-with-country-code) |
+| OTP / PIN digits | [`FieldFlowOTP`](#otp--pin) |
+| Card / phone / currency / date mask | [`FieldFlowMaskedInput`](#masked-inputs) |
+| Card number + expiry + CVC | [`FieldFlowCreditCard`](#credit-card-group) |
+| Date / time / datetime | [`FieldFlowDateTimePicker`](#date--time-picker) |
+| Checkbox / radio / switch | [`Checkbox, radio & switch`](#checkbox-radio--switch) |
+| Multi-value chips (skills, tags) | [`FieldFlowTags`](#tags--chip-input) |
+| Single or multi select | [`FieldFlowDropdown`](#dropdown--select-single--multiple) |
+| Async search / typeahead | [`FieldFlowTypeahead`](#async-typeahead) |
+| File / image upload (pluggable picker) | [`FieldFlowUpload`](#file--image-upload) |
+| Star rating | [`FieldFlowRating`](#rating--slider--number-stepper) |
+| Range slider | [`FieldFlowSlider`](#rating--slider--number-stepper) |
+| +/- quantity stepper | [`FieldFlowNumberStepper`](#rating--slider--number-stepper) |
+| Signature pad | [`FieldFlowSignature`](#signature-pad) |
+| Plan / filter pill tabs | [`FieldFlowSegmented`](#motion--ui) |
+| Long bio / notes | [`DescriptionField`](#description-fields) |
+| Chat composer + attachments | [`ChatInput`](#chat-input) |
+
+### Form engine
+
+| You need… | Use |
+| --------- | --- |
+| Full form state + submit | [`useFieldFlowForm`](#validation) |
+| Sync / async / cross-field rules | [Validation](#validation) · [Zod](#zod-optional) |
+| Server / API field errors (422) | [`setErrors` / `setFieldError`](#server-errors) |
+| Localized validation messages | [`locale` / `messages`](#localized-validation) |
+| Multi-step wizard | [`useFieldFlowSteps`](#multi-step-wizard) + [`FieldFlowStepper`](#multi-step-wizard) |
+| Warn before leaving dirty form | [`useFieldFlowDirtyGuard`](#dirty-leave-guard) |
+| Show / hide / require fields by values | [Conditional fields](#conditional-fields--field-arrays) |
+| Repeatable rows (guests, line items) | [`useFieldFlowArray`](#conditional-fields--field-arrays) |
+| Resume unfinished forms | [`useFieldFlowDraft`](#draft-resume) + [`FieldFlowDraftBanner`](#draft-resume) |
+| Keyboard next / done across fields | [`useKeyboardManager`](#keyboard--form-navigation) + [`KeyboardAwareFormWrapper`](#keyboard--form-navigation) |
+| Friction analytics + a11y on failed submit | [Form intelligence](#form-intelligence) |
+| Already on React Hook Form | [`FieldFlowController`](#react-hook-form-adapter) |
+
+### UI polish & branding
+
+| You need… | Use |
+| --------- | --- |
+| Group fields in a card / collapse | [`FieldFlowSection`](#motion--ui) |
+| Focus glow, error shake, success pop | [`motion` on inputs](#motion--ui) · `useFieldMotion` |
+| `+92` / `$` / `kg` inside the field | [`prefix` / `suffix`](#motion--ui) |
+| Email domain / dial-code chips | [`suggestions`](#smart-suggestion-chips) · [`FieldFlowAffordance`](#smart-suggestion-chips) |
+| Password meter | [`showStrength`](#password-strength) |
+| Look: outlined / filled / underline / floating | [Variants](#variants) |
+| Built-in icons (no icon pack) | [Icons](#icons) |
+| Brand colors in one line | [`themePresets`](#theming) · [`FieldFlowThemeProvider`](#theming) |
+
+### Helpers (also exported)
+
+Masks (`applyMask`, `unmask`, …) · password strength (`evaluatePasswordStrength`) · affordance helpers · a11y (`focusFirstError`, `announceForAccessibility`) · validators · Zod adapters · `FieldFlowIcon` / `renderFieldFlowIcon`
+
+**Full walkthrough:** [Quick start](#quick-start) · [Try it](#try-it-expo--snack) · [Public API](#public-api-at-a-glance)
+
+---
+
+## What's new in 0.5.0
+
+| Addition | What you get |
+| -------- | ------------ |
+| **Smart Affordance** | Email / phone / currency suggestion chips |
+| **Form Intelligence** | Friction report + autofocus / announce on failed submit |
+| **Conditional fields** | `showWhen` / `requiredWhen` / `disabledWhen` |
+| **Field arrays** | `useFieldFlowArray` |
+| **Draft resume** | `useFieldFlowDraft` + `FieldFlowDraftBanner` |
+| **Password strength** | `showStrength` / `FieldFlowPasswordStrength` |
+| **Tags** | `FieldFlowTags` |
+| **React Hook Form** | `FieldFlowController` / `FieldFlowTagsController` |
+| **Motion UI** | Glow, shake, fade, success pop (`motion` prop) |
+| **Sections** | `FieldFlowSection` |
+| **Theme presets** | `themePresets.soft` / `warm` / `teal` / `midnight` / `contrast` |
+| **Prefix / suffix** | Inline affixes on inputs |
+| **Segmented** | `FieldFlowSegmented` |
+| **Multi-step wizard** | `useFieldFlowSteps` + `FieldFlowStepper` |
+| **Phone + country** | `FieldFlowPhone` |
+| **File upload** | `FieldFlowUpload` (inject your picker) |
+| **Typeahead** | `FieldFlowTypeahead` (async `fetchOptions`) |
+| **Server errors** | `setErrors` / `setFieldError` / `clearErrors` |
+| **Rating / slider / +/-** | `FieldFlowRating`, `FieldFlowSlider`, `FieldFlowNumberStepper` |
+| **Dirty leave guard** | `useFieldFlowDirtyGuard` + `isDirty` |
+| **i18n messages** | `locale` / `messages` (`en` `es` `fr` `de` `pt` `ar`) |
+| **Credit card group** | `FieldFlowCreditCard` |
+| **Signature pad** | `FieldFlowSignature` |
+
+Still from **0.4.0:** OTP, masks, date/time, checkbox/radio/switch, variants, icons, async + cross-field validation, Zod, Expo.
+
+> **Note:** since 0.4.0, `validateField` / `validateAll` return `Promise<boolean>`.
 
 ---
 
@@ -18,13 +117,16 @@ npm install rn-inputforge
 yarn add rn-inputforge
 ```
 
-That's it — this is a pure JavaScript/TypeScript package (no native code), so on a bare React Native CLI project there is **no pod install step and no manual linking** required. If you're on iOS and your project's Podfile does a full `pod install` on every dependency change anyway, running it won't hurt, it's just not required for this package.
+That's it — this is a pure JavaScript/TypeScript package (no native code), so there is **no pod install step and no manual linking** required on bare React Native CLI. Same install works in **Expo** (Managed or Dev Client) — just `npx expo install` is not required for this package because it has no native dependencies; `npm install rn-inputforge` / `yarn add rn-inputforge` is enough.
 
 ### Requirements
 
 - `react` >= 18 (tested against 19.2.x)
 - `react-native` >= 0.73 (tested against 0.86.x)
+- Works with Expo SDK that ships RN ≥ 0.73
 - TypeScript is optional but recommended (type defs are bundled)
+- `zod` is an **optional** peer dependency (only if you use the Zod helpers)
+- `react-hook-form` is an **optional** peer dependency (only if you use `FieldFlowController`)
 
 ---
 
@@ -68,6 +170,24 @@ Setting `type="email"` automatically wires up the email keyboard, disables autoc
 | `description` | default, multi-line  | used internally by `DescriptionField` |
 | `chat`        | default              | used internally by `ChatInput`        |
 
+### Core `FieldFlowInput` props (cheat sheet)
+
+| Prop | Purpose |
+| ---- | ------- |
+| `type` | Keyboard + defaults (`email`, `password`, `phone`, …) |
+| `variant` | `outlined` \| `filled` \| `underline` \| `floating` |
+| `label` / `helperText` / `errorText` / `successText` | Copy + states |
+| `rules` / `validateOnChange` | Built-in validation |
+| `leftIcon` / `rightIcon` / `iconSize` / `clearable` | Icons (built-in name or custom node) |
+| `prefix` / `suffix` | Inline affix text or node |
+| `suggestions` | Smart chips (`true`, `'email'`, custom list) |
+| `showStrength` | Password strength meter |
+| `motion` | Micro-interactions (default `true`) |
+| `maxLength` / `showCharacterCount` | Limits + counter |
+| `theme` / style props | Per-field override |
+
+All standard `TextInput` props still pass through (placeholder, `returnKeyType`, etc.).
+
 ---
 
 ## Validation
@@ -112,7 +232,613 @@ const form = useFieldFlowForm({
 />;
 ```
 
-`form.submit()` validates every field and only calls `onSubmit` if everything passes.
+`form.submit()` validates every field (including async + cross-field rules) and only calls `onSubmit` if everything passes.
+
+### Cross-field & async validation
+
+```tsx
+const form = useFieldFlowForm({
+  initialValues: { password: '', confirm: '', email: '' },
+  rules: {
+    password: { required: true, minLength: 8 },
+    confirm: { required: true },
+    email: { required: true, email: true },
+  },
+  crossFieldRules: [
+    {
+      target: 'confirm',
+      deps: ['password'],
+      validate: v =>
+        v.password === v.confirm
+          ? { valid: true }
+          : { valid: false, message: 'Passwords must match' },
+    },
+  ],
+  asyncValidators: {
+    email: async value => {
+      const taken = await api.isEmailTaken(value);
+      return taken
+        ? { valid: false, message: 'Email is already taken' }
+        : { valid: true };
+    },
+  },
+});
+
+// form.validating.email === true while the async check runs
+// form.isValidating === true if any async validator is in flight
+```
+
+> **Note (0.4.0):** `validateField` and `validateAll` are now `async` and return `Promise<boolean>`.
+
+### Zod (optional)
+
+```bash
+npm install zod
+```
+
+```tsx
+import { z } from 'zod';
+import { useFieldFlowForm, zodFormValidate } from 'rn-inputforge';
+
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+const form = useFieldFlowForm({
+  initialValues: { email: '', password: '' },
+  formValidate: zodFormValidate(schema),
+  onSubmit: async values => api.login(values),
+});
+```
+
+Also exported: `zodToFormErrors`, `createZodSubmitGuard`, `fieldRulesFromZodString`.
+
+---
+
+## Try it (Expo / Snack)
+
+1. Create a blank Snack at [snack.expo.dev](https://snack.expo.dev).
+2. Add dependency `rn-inputforge` (and `react-hook-form` if you try the RHF adapter).
+3. Paste any snippet from this README or copy `example/App.tsx` from the repo.
+
+Same install works in a local Expo app:
+
+```bash
+npx create-expo-app MyFormDemo
+cd MyFormDemo
+npx expo install rn-inputforge
+```
+
+---
+
+## Password strength
+
+```tsx
+<FieldFlowInput
+  type="password"
+  label="Password"
+  value={password}
+  onChangeText={setPassword}
+  showStrength
+  // or: showStrength={{ showRules: true, rules: customRules }}
+/>
+
+// Standalone meter
+<FieldFlowPasswordStrength password={password} />
+```
+
+Pure helper: `evaluatePasswordStrength(password)` → `{ level, progress, passed, failed }`.
+
+---
+
+## Tags / chip input
+
+```tsx
+const [skills, setSkills] = useState<string[]>([]);
+
+<FieldFlowTags
+  label="Skills"
+  value={skills}
+  onChange={setSkills}
+  maxTags={8}
+  placeholder="Type a skill and press Enter"
+  helperText="Comma or Enter to add"
+/>
+```
+
+---
+
+## React Hook Form adapter
+
+```bash
+npm install react-hook-form
+```
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { FieldFlowController, FieldFlowTagsController } from 'rn-inputforge';
+
+const { control, handleSubmit } = useForm({
+  defaultValues: { email: '', skills: [] as string[] },
+});
+
+<FieldFlowController
+  control={control}
+  name="email"
+  type="email"
+  label="Email"
+  suggestions
+  rules={{ required: 'Email is required' }}
+/>
+
+<FieldFlowTagsController
+  control={control}
+  name="skills"
+  label="Skills"
+  rules={{ validate: v => (v?.length ? true : 'Add at least one skill') }}
+/>
+```
+
+Also exported: `mapRhfToFieldFlowProps` for custom `Controller` renders.
+
+---
+
+## Smart suggestion chips
+
+Show quick-complete chips while a field is focused — a UX gap most RN input kits skip:
+
+```tsx
+// Infer from type: email → @gmail.com…, phone → +1/+44…, number/decimal → $/€/£
+<FieldFlowInput type="email" label="Email" value={email} onChangeText={setEmail} suggestions />
+
+// Force a preset or pass a custom list
+<FieldFlowInput type="phone" suggestions="phone" value={phone} onChangeText={setPhone} />
+<FieldFlowInput suggestions={['@company.com', '@partner.io']} value={work} onChangeText={setWork} />
+
+// Standalone bar (e.g. above the keyboard area)
+<FieldFlowAffordance
+  kind="email"
+  value={email}
+  onSelect={setEmail}
+/>
+```
+
+Helpers exported: `applyEmailDomainSuggestion`, `DEFAULT_EMAIL_DOMAINS`, `DEFAULT_PHONE_DIAL_CODES`, `DEFAULT_CURRENCY_SYMBOLS`.
+
+---
+
+## Form intelligence
+
+Enable friction tracking and accessibility autopilot on the form hook:
+
+```tsx
+const form = useFieldFlowForm({
+  initialValues: { email: '', password: '' },
+  rules: { email: { required: true, email: true }, password: { required: true, minLength: 8 } },
+  fieldOrder: ['email', 'password'],
+  intelligence: {
+    onReport: report => console.log(report.mostFriction),
+    // focusFirstError: true (default)
+    // announceErrors: true (default) — VoiceOver / TalkBack
+  },
+  onSubmit: async values => api.login(values),
+});
+
+<FieldFlowInput
+  ref={r => form.registerFieldRef('email', { current: r })}
+  label="Email"
+  {...form.getInputProps('email')}
+  suggestions
+/>;
+
+// After interactions:
+form.intelligence?.getReport();
+// → { sessionMs, submitAttempts, fields: { email: { focusCount, errorCount, totalFocusMs, … } }, mostFriction }
+```
+
+Standalone helpers: `useFormIntelligence`, `focusFirstError`, `announceForAccessibility`.
+
+---
+
+## Conditional fields & field arrays
+
+```tsx
+const form = useFieldFlowForm({
+  initialValues: { accountType: 'personal', company: '', taxId: '' },
+  conditions: {
+    company: {
+      showWhen: v => v.accountType === 'business',
+      requiredWhen: v => v.accountType === 'business',
+    },
+    taxId: {
+      showWhen: v => v.accountType === 'business',
+      disabledWhen: v => v.accountType !== 'business',
+    },
+  },
+});
+
+{form.isVisible('company') && (
+  <FieldFlowInput label="Company" {...form.getInputProps('company')!} />
+)}
+```
+
+Repeatable groups:
+
+```tsx
+import { useFieldFlowArray, FieldFlowInput } from 'rn-inputforge';
+
+const guests = useFieldFlowArray({
+  createItem: () => ({ name: '', email: '' }),
+  min: 1,
+  max: 5,
+});
+
+{guests.items.map((guest, i) => (
+  <FieldFlowInput
+    key={i}
+    label={`Guest ${i + 1}`}
+    value={guest.name}
+    onChangeText={name => guests.update(i, g => ({ ...g, name }))}
+  />
+))}
+<Button title="Add guest" disabled={guests.isMax} onPress={() => guests.append()} />
+```
+
+---
+
+## Draft resume
+
+Persist form values with any storage backend (AsyncStorage, MMKV, custom). No hard dependency:
+
+```tsx
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { useFieldFlowDraft, FieldFlowDraftBanner, useFieldFlowForm } from 'rn-inputforge';
+
+const form = useFieldFlowForm({ initialValues: { name: '', email: '' }, /* … */ });
+
+const draft = useFieldFlowDraft({
+  key: 'signup-v1',
+  storage: {
+    getItem: k => AsyncStorage.getItem(k),
+    setItem: (k, v) => AsyncStorage.setItem(k, v),
+    removeItem: k => AsyncStorage.removeItem(k),
+  },
+  values: form.values,
+  onRestore: form.setValues,
+  exclude: ['password'], // never persist secrets
+  ttlMs: 7 * 24 * 60 * 60 * 1000,
+});
+
+<FieldFlowDraftBanner
+  visible={draft.hasDraft}
+  savedAt={draft.draftSavedAt}
+  onResume={draft.resume}
+  onDiscard={draft.discard}
+/>;
+```
+
+On successful submit, call `await draft.clear()` so the banner doesn't reappear.
+
+---
+
+## Multi-step wizard
+
+```tsx
+import { useFieldFlowForm, useFieldFlowSteps, FieldFlowStepper, FieldFlowInput } from 'rn-inputforge';
+
+const form = useFieldFlowForm({
+  initialValues: { name: '', email: '', bio: '' },
+  rules: {
+    name: { required: true },
+    email: { required: true, email: true },
+  },
+  onSubmit: async values => api.signup(values),
+});
+
+const wizard = useFieldFlowSteps({
+  values: form.values,
+  validateFields: form.validateFields,
+  onComplete: form.submit,
+  steps: [
+    { id: 'profile', title: 'Profile', fields: ['name'] },
+    { id: 'contact', title: 'Contact', fields: ['email'] },
+    { id: 'about', title: 'About', fields: ['bio'] },
+  ],
+});
+
+<>
+  <FieldFlowStepper steps={wizard.steps} stepIndex={wizard.stepIndex} onStepPress={wizard.goTo} />
+  {wizard.step.id === 'profile' && <FieldFlowInput label="Name" {...form.getInputProps('name')!} />}
+  {wizard.step.id === 'contact' && <FieldFlowInput type="email" label="Email" {...form.getInputProps('email')!} />}
+  {wizard.step.id === 'about' && <FieldFlowInput label="Bio" {...form.getInputProps('bio')!} />}
+  <Button title={wizard.isLast ? 'Submit' : 'Next'} onPress={() => wizard.next()} />
+  {!wizard.isFirst && <Button title="Back" onPress={wizard.back} />}
+</>;
+```
+
+---
+
+## Server errors
+
+Map API 422 responses straight into the form:
+
+```tsx
+try {
+  await api.signup(form.values);
+} catch (err) {
+  // { email: 'Already taken', password: 'Too weak' }
+  form.setErrors(err.fieldErrors);
+  // or: form.setFieldError('email', 'Already taken');
+  // form.clearErrors('email') / form.clearErrors()
+}
+```
+
+Also available: `form.isDirty`, `form.dirtyFields`, `form.validateFields(['email', 'password'])`.
+
+---
+
+## Localized validation
+
+```tsx
+const form = useFieldFlowForm({
+  initialValues: { email: '' },
+  rules: { email: { required: true, email: true } },
+  locale: 'es', // en | es | fr | de | pt | ar
+  // or: messages: createValidationMessages({ required: 'Custom…' }, 'en'),
+});
+```
+
+Helpers: `getValidationMessages('fr')`, `validationMessageCatalogs`, `createValidationMessages`.
+
+---
+
+## Dirty leave guard
+
+```tsx
+import { useFieldFlowDirtyGuard } from 'rn-inputforge';
+
+const { confirmIfDirty } = useFieldFlowDirtyGuard({
+  isDirty: form.isDirty,
+  onDiscard: form.reset,
+});
+
+// React Navigation:
+navigation.addListener('beforeRemove', async e => {
+  if (!form.isDirty) return;
+  e.preventDefault();
+  if (await confirmIfDirty()) navigation.dispatch(e.data.action);
+});
+```
+
+Android hardware back is intercepted automatically when dirty.
+
+---
+
+## Phone with country code
+
+```tsx
+import { FieldFlowPhone } from 'rn-inputforge';
+
+const [phone, setPhone] = useState(null);
+
+<FieldFlowPhone
+  label="Mobile"
+  value={phone}
+  onChange={setPhone}
+  defaultCountryCode="PK"
+  required
+/>;
+// phone.e164 → "+923001234567"
+```
+
+---
+
+## File / image upload
+
+Pure JS — you inject the picker (Expo or RN):
+
+```tsx
+import * as ImagePicker from 'expo-image-picker';
+import { FieldFlowUpload } from 'rn-inputforge';
+
+<FieldFlowUpload
+  label="ID photo"
+  maxFiles={2}
+  value={files}
+  onChange={setFiles}
+  pick={async () => {
+    const res = await ImagePicker.launchImageLibraryAsync({ mediaTypes: ['images'] });
+    if (res.canceled || !res.assets[0]) return null;
+    const a = res.assets[0];
+    return { uri: a.uri, name: a.fileName ?? 'photo.jpg', mimeType: a.mimeType, size: a.fileSize };
+  }}
+/>;
+```
+
+---
+
+## Async typeahead
+
+```tsx
+import { FieldFlowTypeahead } from 'rn-inputforge';
+
+<FieldFlowTypeahead
+  label="City"
+  value={city}
+  displayValue={cityLabel}
+  onChange={(value, option) => {
+    setCity(value);
+    setCityLabel(option?.label ?? '');
+  }}
+  fetchOptions={async query => {
+    const rows = await api.searchCities(query);
+    return rows.map(r => ({ label: r.name, value: r.id }));
+  }}
+  minChars={2}
+/>;
+```
+
+---
+
+## Rating / slider / number stepper
+
+```tsx
+<FieldFlowRating label="Experience" value={rating} onChange={setRating} />
+<FieldFlowSlider label="Budget" value={budget} onChange={setBudget} min={0} max={1000} step={50} />
+<FieldFlowNumberStepper label="Guests" value={guests} onChange={setGuests} min={1} max={12} />
+```
+
+---
+
+## Credit card group
+
+```tsx
+import { FieldFlowCreditCard } from 'rn-inputforge';
+
+const [card, setCard] = useState({ number: '', expiry: '', cvc: '', name: '' });
+
+<FieldFlowCreditCard value={card} onChange={setCard} showName required />;
+```
+
+---
+
+## Signature pad
+
+```tsx
+import { FieldFlowSignature } from 'rn-inputforge';
+
+<FieldFlowSignature
+  label="Sign to confirm"
+  value={signature}
+  onChange={setSignature}
+  required
+/>;
+// signature.isEmpty / signature.strokes
+```
+
+---
+
+## Variants
+
+Every text-like field (`FieldFlowInput`, `FieldFlowMaskedInput`, date picker trigger) supports:
+
+| `variant`    | Look                                      |
+| ------------ | ----------------------------------------- |
+| `outlined`   | Bordered box (default)                    |
+| `filled`     | Soft filled background                    |
+| `underline`  | Bottom border only                        |
+| `floating`   | Label animates into the border when filled / focused |
+
+```tsx
+<FieldFlowInput variant="floating" label="Email" type="email" value={email} onChangeText={setEmail} />
+<FieldFlowInput variant="underline" label="Name" leftIcon="user" value={name} onChangeText={setName} />
+```
+
+## Icons
+
+Built-in, dependency-free icons — pass a name **or** any custom React node:
+
+```tsx
+<FieldFlowInput leftIcon="mail" rightIcon={<MyLucideIcon />} />
+<FieldFlowInput type="email" />           // auto leftIcon="mail"
+<FieldFlowInput type="password" />        // auto leftIcon="lock" + show/hide
+<FieldFlowMaskedInput mask="card" />      // auto leftIcon="creditCard"
+```
+
+Built-in names include: `eye`, `eyeOff`, `clear`, `check`, `alert`, `search`, `send`, `camera`, `image`, `paperclip`, `mic`, `mapPin`, `chevronDown/Up/Left/Right`, `calendar`, `clock`, `creditCard`, `currency`, `phone`, `mail`, `lock`, `user`, `key`, `hash`, `otp`, `radio`, `radioFilled`, `switch`, `star`, `plus`, `minus`, `info`, `home`, `settings`, `edit`, `trash`, `link`, `globe`, `file`, `folder`, `bell`, `heart`, `spinner`.
+
+Use `FieldFlowIcon` / `renderFieldFlowIcon` anywhere in your app. Set `iconSize` on components to scale them. Pass `leftIcon={null}` / `undefined` carefully — omit the prop to keep defaults, or pass a custom node to replace.
+
+## OTP / PIN
+
+```tsx
+import { FieldFlowOTP } from 'rn-inputforge';
+
+<FieldFlowOTP
+  label="Verification code"
+  leftIcon="otp"
+  length={6}
+  value={code}
+  onChangeText={setCode}
+  onComplete={value => verify(value)}
+  cellSize={48}
+/>
+```
+
+Supports paste/autofill (`textContentType="oneTimeCode"`), backspace navigation, secure mode, custom `renderCell`, cell styles, and icons.
+
+---
+
+## Masked inputs
+
+```tsx
+import { FieldFlowMaskedInput } from 'rn-inputforge';
+
+<FieldFlowMaskedInput mask="phone" label="Phone" value={phone} onChangeText={setPhone} />
+<FieldFlowMaskedInput mask="card" label="Card" valueMode="raw" value={card} onChangeText={(_, raw) => setCard(raw)} />
+<FieldFlowMaskedInput mask="currency" maskOptions={{ currencySymbol: '$' }} value={amount} onChangeText={setAmount} />
+<FieldFlowMaskedInput mask="date" label="Date" value={date} onChangeText={setDate} />
+<FieldFlowMaskedInput mask="custom" maskOptions={{ pattern: '###-##-####' }} value={ssn} onChangeText={setSsn} />
+```
+
+Built-in masks: `phone`, `card`, `currency`, `date`, `custom` (pattern with `#` = digit). `onChangeText(formatted, raw)` always receives both; `valueMode` controls which string you store (`'formatted'` default, or `'raw'`).
+
+Low-level helpers are also exported: `applyMask`, `formatMasked`, `unmask`, `digitsOnly`.
+
+---
+
+## Date & time picker
+
+Pure JS calendar / time sheet (no native modules):
+
+```tsx
+import { FieldFlowDateTimePicker } from 'rn-inputforge';
+
+<FieldFlowDateTimePicker mode="date" label="Birthday" value={dob} onChange={setDob} clearable />
+<FieldFlowDateTimePicker mode="time" label="Start time" value={time} onChange={setTime} hourCycle={12} />
+<FieldFlowDateTimePicker
+  mode="datetime"
+  label="Appointment"
+  value={appt}
+  onChange={setAppt}
+  leftIcon="calendar"
+  minimumDate="2020-01-01"
+  formatDisplay={(d) => d.toLocaleString()}
+/>
+```
+
+Fully customizable: icons, labels, confirm/cancel text, `renderTrigger`, `formatDisplay`, min/max dates, theme, styles.
+
+## Checkbox, radio & switch
+
+```tsx
+import { FieldFlowCheckbox, FieldFlowRadio, FieldFlowSwitch } from 'rn-inputforge';
+
+<FieldFlowCheckbox
+  label="I agree to the Terms"
+  leftIcon="file"
+  checkedIcon="check"
+  value={accepted}
+  onChange={setAccepted}
+  required
+/>
+
+<FieldFlowRadio
+  label="Plan"
+  leftIcon="star"
+  value={plan}
+  onChange={setPlan}
+  options={[
+    { label: 'Starter', value: 'starter', icon: 'home' },
+    { label: 'Pro', value: 'pro', description: 'Most popular', icon: 'star' },
+  ]}
+/>
+
+<FieldFlowSwitch label="Push notifications" leftIcon="bell" value={pushOn} onChange={setPushOn} />
+```
+
+Override colors (`checkedColor`, `onTrackColor`, …), icons, sizes, and `renderOption` when you need full control.
 
 ---
 
@@ -225,15 +951,115 @@ Handles expandable height, keyboard-avoiding behavior, and a send button that's
 
 ---
 
-## Icons
+## Custom render slots
+
+Most controls accept optional render props so apps can keep FieldFlow behavior and swap chrome:
+
+| Component | Slots |
+| --------- | ----- |
+| `FieldFlowUpload` | `renderDropzone`, `renderFile` |
+| `FieldFlowTypeahead` | `renderOption`, `renderEmpty` |
+| `FieldFlowRating` | `renderStar` |
+| `FieldFlowSlider` | `renderThumb` |
+| `FieldFlowNumberStepper` | `renderDecrease`, `renderIncrease`, `renderValue` |
+| `FieldFlowPhone` | `renderDialButton`, `renderCountryOption` |
+| `FieldFlowStepper` | `renderStep`, `headerRight` |
+| `FieldFlowSignature` | `renderClear`, `renderPlaceholder` |
+
+```tsx
+<FieldFlowRating
+  value={rating}
+  onChange={setRating}
+  renderStar={({ filled, size }) => (
+    <Text style={{ fontSize: size }}>{filled ? '🟢' : '⚪'}</Text>
+  )}
+/>
+
+<FieldFlowUpload
+  pick={myPicker}
+  value={files}
+  onChange={setFiles}
+  renderFile={({ file, remove }) => (
+    <Pressable onPress={remove}>
+      <Text>{file.name} ✕</Text>
+    </Pressable>
+  )}
+/>
+```
+
+Defaults stay unchanged when you omit these props.
+
+---
+
+## Motion & UI
+
+### Field motion
+
+`FieldFlowInput` ships with micro-interactions on by default (`motion={true}`):
+
+- **Focus glow** — soft ring around the field chrome
+- **Error shake** — brief horizontal shake when validation fails
+- **Message fade** — helper / error text cross-fades in
+- **Success pop** — right-side success icon scales in
+
+All of this uses React Native `Animated` (no Reanimated) and **respects OS Reduce Motion**. Pass `motion={false}` to disable per field, or use `useReducedMotion` / `useFieldMotion` if you build custom chrome.
+
+```tsx
+<FieldFlowInput label="Email" type="email" value={email} onChangeText={setEmail} motion />
+```
+
+### Prefix & suffix
+
+Inline affixes sit inside the field before / after the value (alongside icons):
+
+```tsx
+<FieldFlowInput
+  type="phone"
+  label="Phone"
+  prefix="+92"
+  value={phone}
+  onChangeText={setPhone}
+/>
+
+<FieldFlowInput
+  type="decimal"
+  label="Weight"
+  suffix="kg"
+  value={weight}
+  onChangeText={setWeight}
+/>
+```
+
+### Form sections
 
-FieldFlow ships a small, dependency-free icon set (`eye`, `eyeOff`, `clear`, `check`, `alert`, `search`, `send`, `camera`, `image`, `paperclip`, `mic`, `mapPin`, `spinner`) so you don't need to install `react-native-svg` or a vector-icon library just to use text fields with icons:
+Group related fields into a themed card with optional collapse:
 
 ```tsx
-<FieldFlowInput leftIcon="search" rightIcon={<MyCustomIcon />} />
+import { FieldFlowSection, FieldFlowInput } from 'rn-inputforge';
+
+<FieldFlowSection title="Account" description="How we’ll reach you" icon="mail" collapsible>
+  <FieldFlowInput type="email" label="Email" value={email} onChangeText={setEmail} />
+  <FieldFlowInput type="phone" label="Phone" prefix="+1" value={phone} onChangeText={setPhone} />
+</FieldFlowSection>;
 ```
 
-Any prop that accepts an icon also accepts a raw `ReactNode`, so you can swap in your own icon library (e.g. `react-native-vector-icons`, `lucide-react-native`) at any time without changing anything else.
+### Segmented control
+
+Animated pill control for plan pickers, account type, filters:
+
+```tsx
+import { FieldFlowSegmented } from 'rn-inputforge';
+
+<FieldFlowSegmented
+  label="Account type"
+  value={accountType}
+  onChange={setAccountType}
+  options={[
+    { label: 'Personal', value: 'personal', icon: 'user' },
+    { label: 'Business', value: 'business', icon: 'globe' },
+  ]}
+/>;
+```
 
 ---
 
@@ -242,8 +1068,14 @@ Any prop that accepts an icon also accepts a raw `ReactNode`, so you can swap in
 Wrap your app (or just a screen) in `FieldFlowThemeProvider` and override only what you need — everything else falls back to the default theme:
 
 ```tsx
-import { FieldFlowThemeProvider } from 'rn-inputforge';
+import { FieldFlowThemeProvider, themePresets } from 'rn-inputforge';
+
+// One-liner brand start
+<FieldFlowThemeProvider theme={themePresets.soft}>
+  <App />
+</FieldFlowThemeProvider>
 
+// Or merge your own tokens
 <FieldFlowThemeProvider
   theme={{
     colors: { borderFocused: '#7C3AED', labelFocused: '#7C3AED' },
@@ -254,8 +1086,49 @@ import { FieldFlowThemeProvider } from 'rn-inputforge';
 </FieldFlowThemeProvider>;
 ```
 
+**Bundled presets:** `default`, `dark`, `soft`, `warm`, `teal`, `midnight`, `contrast`. Use `getThemePreset('teal')` if you prefer a function call.
+
 You can also pass a one-off `theme` prop directly to any single field to override it locally, or use the bundled `darkTheme` as a starting point for dark mode.
 
+Theme tokens you can override: `colors.*`, `spacing.*`, `typography.*`, `animation.*` (see `FieldFlowTheme` in the package types).
+
+---
+
+## Public API at a glance
+
+Import anything below from `'rn-inputforge'`:
+
+```ts
+// Components
+FieldFlowInput, FieldFlowOTP, FieldFlowMaskedInput, FieldFlowDateTimePicker,
+FieldFlowCheckbox, FieldFlowRadio, FieldFlowSwitch, FieldFlowDropdown,
+FieldFlowTags, FieldFlowSegmented, FieldFlowSection, FieldFlowAffordance,
+FieldFlowDraftBanner, FieldFlowPasswordStrength, FieldFlowStepper,
+FieldFlowPhone, FieldFlowUpload, FieldFlowTypeahead, FieldFlowRating,
+FieldFlowSlider, FieldFlowNumberStepper, FieldFlowCreditCard, FieldFlowSignature,
+DescriptionField, ChatInput, KeyboardAwareFormWrapper
+
+// Form hooks
+useFieldFlowForm, useFieldFlowArray, useFieldFlowDraft,
+useFieldFlowSteps, useFieldFlowDirtyGuard,
+useKeyboardManager, useFieldState, useFormIntelligence
+
+// Motion / Theming / i18n
+useFieldMotion, useReducedMotion
+FieldFlowThemeProvider, themePresets, getThemePreset, defaultTheme, darkTheme
+getValidationMessages, createValidationMessages, validationMessageCatalogs
+
+// Adapters / Icons
+FieldFlowController, FieldFlowTagsController, mapRhfToFieldFlowProps
+FieldFlowIcon, renderFieldFlowIcon
+
+// Validation, masks, phone, a11y
+runRules, zod helpers, applyMask, unmask, DEFAULT_COUNTRY_DIALS,
+evaluatePasswordStrength, focusFirstError, announceForAccessibility, …
+```
+
+Types for props, themes, rules, and draft storage are exported alongside the values. See `example/App.tsx` for a full usage reference screen.
+
 ---
 
 ## Project structure
@@ -264,18 +1137,34 @@ You can also pass a one-off `theme` prop directly to any single field to overrid
 rn-inputforge/
 ├── src/
 │   ├── components/
-│   │   ├── FieldFlowInput/        core input (all field types, icons, states)
-│   │   ├── DescriptionField/      auto-growing multiline field
-│   │   ├── ChatInput/             chat composer + attachment toolbar
-│   │   ├── FieldFlowDropdown/     single/multi select — bottom sheet, popup, or inline
+│   │   ├── FieldFlowInput/            core input + variants + motion + affixes
+│   │   ├── FieldFlowSection/          themed form card / collapse
+│   │   ├── FieldFlowSegmented/        animated pill control
+│   │   ├── FieldFlowAffordance/       standalone suggestion chip bar
+│   │   ├── FieldFlowOTP/              OTP / PIN digit cells
+│   │   ├── FieldFlowMaskedInput/      phone, card, currency, date, custom masks
+│   │   ├── FieldFlowDateTimePicker/   date / time / datetime (pure JS)
+│   │   ├── FieldFlowCheckbox/         themed checkbox
+│   │   ├── FieldFlowRadio/            radio group
+│   │   ├── FieldFlowSwitch/           animated switch
+│   │   ├── FieldFlowDraftBanner/      resume-draft UI
+│   │   ├── FieldFlowTags/             multi-value chip input
+│   │   ├── FieldFlowPasswordStrength/ strength meter + rules
+│   │   ├── DescriptionField/          auto-growing multiline field
+│   │   ├── ChatInput/                 chat composer + attachment toolbar
+│   │   ├── FieldFlowDropdown/         single/multi select
 │   │   └── KeyboardAwareFormWrapper/
-│   ├── hooks/                     useFieldFlowForm, useKeyboardManager, useFieldState
-│   ├── theme/                     ThemeProvider + default/dark themes
-│   ├── validation/                validators + useValidation
-│   ├── icons/                     dependency-free icon set
-│   ├── utils/                     keyboard-type resolution, formatters
-│   └── index.ts                   public API
-├── example/App.tsx                full usage reference (form + chat screen)
+│   ├── adapters/                      react-hook-form Controllers
+│   ├── hooks/                         form, array, draft, intelligence, keyboard
+│   ├── intelligence/                  a11y helpers + friction report types
+│   ├── motion/                        field motion + reduce-motion hooks
+│   ├── theme/                         ThemeProvider + presets + default/dark
+│   ├── validation/                    validators, Zod adapter
+│   ├── icons/                         dependency-free icon set
+│   ├── utils/                         masks, affordance, password strength, …
+│   ├── __tests__/                     Jest unit tests
+│   └── index.ts                       public API
+├── example/App.tsx                    full usage reference
 ├── package.json
 └── tsconfig*.json
 ```