rn-inputforge 0.4.0 → 0.5.1

package/README.md

@@ -1,33 +1,131 @@
 # rn-inputforge
 
-A production-ready, highly customizable input field system for **React Native** (bare CLI **and Expo**) — text, email, number, phone, password, search, OTP/PIN, masked inputs, date/time picker, checkbox/radio/switch, description, and chat inputs, plus a fully customizable single/multi-select dropdown (bottom sheet, popup, or inline), with built-in validation (sync, async, cross-field, optional Zod), 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 new in 0.4.0
+## 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) |
+| Autofill / password manager hints | [`autofill` / `autofillProfiles`](#autofill-profiles) |
+| Keyboard Prev/Next/Done bar | [`FieldFlowKeyboardToolbar`](#keyboard-toolbar) |
+| Smart paste (OTP / card / address) | [`routeSmartPaste`](#smart-paste) |
+| “N fields left” progress coach | [`FieldFlowCompleteness`](#completeness-coach) |
+| Passkey / SSO / biometric strip | [`FieldFlowAuthActions`](#auth-actions) |
+| JSON schema → form UI | [`FieldFlowSchemaForm`](#schema-form-renderer) |
+| Dev accessibility audit | [`FieldFlowA11yAudit`](#a11y-auditor) |
+| Offline submit retry queue | [`useFieldFlowSubmitQueue`](#offline-submit-queue) |
+| 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) |
+| Density / size / shape / surface | [`density` `size` `shape` `surface` `focusRing`](#visual-system) |
+| Calm tips & alerts | [`FieldFlowInlineAlert`](#visual-system) · [`FieldFlowInfoTip`](#visual-system) |
+| Loading skeletons | [`FieldFlowSkeleton`](#visual-system) |
+| Form intro header | [`FieldFlowFormHeader`](#visual-system) |
+
+### 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)
 
-Upgrading from **0.3.1**? Here's everything added in this release:
+---
+
+## What's new in 0.5.0
 
 | Addition | What you get |
 | -------- | ------------ |
-| **`FieldFlowOTP`** | OTP / PIN digit cells with paste, autofill, and `onComplete` |
-| **`FieldFlowMaskedInput`** | `phone`, `card`, `currency`, `date`, and custom `#` masks |
-| **`FieldFlowDateTimePicker`** | Pure-JS date / time / datetime picker (no native modules) |
-| **`FieldFlowCheckbox`** | Themed checkbox with custom icons & colors |
-| **`FieldFlowRadio`** | Radio group (options can carry icons too) |
-| **`FieldFlowSwitch`** | Animated switch with theme overrides |
-| **Variants** | `outlined` · `filled` · `underline` · `floating` on text fields |
-| **Icons** | Larger built-in set + pass any custom React node anywhere |
-| **Async validation** | `asyncValidators` + `form.validating` / `form.isValidating` |
-| **Cross-field rules** | e.g. password confirm via `crossFieldRules` |
-| **Zod helpers** | Optional `zodFormValidate`, `zodToFormErrors`, etc. |
-| **Expo** | Explicit support — same install, no linking |
-
-**Breaking change:** `validateField` and `validateAll` now return `Promise<boolean>` (needed for async validation). Prefer `await form.validateAll()` or just use `form.submit()`.
-
-Jump to: [OTP](#otp--pin) · [Masked inputs](#masked-inputs) · [Date & time](#date--time-picker) · [Checkbox / radio / switch](#checkbox-radio--switch) · [Variants](#variants) · [Icons](#icons) · [Validation](#validation)
+| **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` |
+| **Autofill profiles** | `autofill` prop + `autofillProfiles.login/signup/…` |
+| **Keyboard toolbar** | `FieldFlowKeyboardToolbar` Prev/Next/Done |
+| **Smart paste** | `routeSmartPaste` / `useSmartPaste` |
+| **Completeness coach** | `useFieldFlowCompleteness` + `FieldFlowCompleteness` |
+| **Auth actions** | `FieldFlowAuthActions` (passkey / SSO / biometric slots) |
+| **Schema form** | `FieldFlowSchemaForm` JSON → UI |
+| **A11y auditor** | `runA11yAudit` + `FieldFlowA11yAudit` (dev) |
+| **Submit queue** | `useFieldFlowSubmitQueue` offline / retry |
+| **Visual system** | Density, size, shape, surface, focus rings |
+| **Inline alert / skeleton / header** | `FieldFlowInlineAlert`, `FieldFlowSkeleton`, `FieldFlowFormHeader` |
+| **Info tips + helper status** | `infoTip`, `helperStatus`, `FieldFlowInfoTip` |
+| **Theme crossfade** | Soft fade when switching presets (`animateTheme`) |
+
+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>`.
 
 ---
 
@@ -52,6 +150,7 @@ That's it — this is a pure JavaScript/TypeScript package (no native code), so
 - 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`)
 
 ---
 
@@ -95,6 +194,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
@@ -203,6 +320,429 @@ Also exported: `zodToFormErrors`, `createZodSubmitGuard`, `fieldRulesFromZodStri
 
 ---
 
+## 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:
@@ -435,13 +975,343 @@ Handles expandable height, keyboard-avoiding behavior, and a send button that's
 
 ---
 
+## Autofill profiles
+
+```tsx
+import { FieldFlowInput, autofillProfiles } from 'rn-inputforge';
+
+<FieldFlowInput type="email" label="Email" autofill={autofillProfiles.signup.email} ... />
+<FieldFlowInput type="password" label="Password" autofill="newPassword" ... />
+<FieldFlowOTP autofill="oneTimeCode" ... /> // or pass through TextInput props
+```
+
+Roles: `email`, `password`, `newPassword`, `oneTimeCode`, `tel`, `name`, `streetAddress`, `ccNumber`, … — see `getAutofillProps` / `autofillProfiles`.
+
+---
+
+## Keyboard toolbar
+
+```tsx
+import {
+  FieldFlowKeyboardToolbar,
+  FIELD_FLOW_KEYBOARD_TOOLBAR_ID,
+  useKeyboardManager,
+} from 'rn-inputforge';
+
+const kb = useKeyboardManager({ order: ['email', 'password'], onSubmit: form.submit });
+
+<>
+  <FieldFlowInput
+    inputAccessoryViewID={FIELD_FLOW_KEYBOARD_TOOLBAR_ID}
+    ...
+  />
+  <FieldFlowKeyboardToolbar
+    nativeID={FIELD_FLOW_KEYBOARD_TOOLBAR_ID}
+    onPrevious={() => kb.focusPrevious(activeId)}
+    onNext={() => kb.focusNext(activeId)}
+    onDone={form.submit}
+    canPrevious={kb.canGoPrevious(activeId)}
+    canNext={kb.canGoNext(activeId)}
+  />
+</>
+```
+
+---
+
+## Smart paste
+
+```tsx
+import { routeSmartPaste, useSmartPaste } from 'rn-inputforge';
+
+const { handlePaste } = useSmartPaste({
+  targets: {
+    otp: r => setCode(r.value),
+    card: r => setCardNumber(r.raw ?? r.value),
+    email: r => form.handleChange('email')(r.value),
+    addressFields: addr => {
+      form.handleChange('street')(addr.street ?? '');
+      form.handleChange('city')(addr.city ?? '');
+    },
+  },
+});
+
+// After Clipboard.getString():
+handlePaste(pastedText);
+```
+
+---
+
+## Completeness coach
+
+```tsx
+import { useFieldFlowCompleteness, FieldFlowCompleteness } from 'rn-inputforge';
+
+const completeness = useFieldFlowCompleteness({
+  values: form.values,
+  requiredFields: ['name', 'email', 'password'],
+});
+
+<FieldFlowCompleteness completeness={completeness} />;
+```
+
+---
+
+## Auth actions
+
+```tsx
+import { FieldFlowAuthActions } from 'rn-inputforge';
+
+<FieldFlowAuthActions
+  actions={[
+    { id: 'passkey', label: 'Passkey', icon: 'key', onPress: signInWithPasskey },
+    { id: 'apple', label: 'Apple', icon: 'user', onPress: signInWithApple },
+    { id: 'google', label: 'Google', icon: 'globe', onPress: signInWithGoogle },
+  ]}
+/>
+```
+
+---
+
+## Schema form renderer
+
+```tsx
+import { FieldFlowSchemaForm, type FieldFlowFormSchema } from 'rn-inputforge';
+
+const schema: FieldFlowFormSchema = {
+  fields: [
+    { name: 'name', type: 'text', label: 'Name', required: true, section: 'profile', autofill: 'name' },
+    { name: 'email', type: 'email', label: 'Email', required: true, section: 'profile' },
+    { name: 'plan', type: 'segmented', label: 'Plan', options: [
+      { label: 'Free', value: 'free' },
+      { label: 'Pro', value: 'pro' },
+    ]},
+  ],
+  sections: [{ id: 'profile', title: 'Profile', icon: 'user' }],
+};
+
+<FieldFlowSchemaForm
+  schema={schema}
+  onSubmit={async values => api.save(values)}
+  renderFooter={({ submit, isSubmitting }) => (
+    <Button title={isSubmitting ? '…' : 'Save'} onPress={() => void submit()} />
+  )}
+/>;
+```
+
+---
+
+## A11y auditor
+
+```tsx
+import { FieldFlowA11yAudit, runA11yAudit } from 'rn-inputforge';
+
+<FieldFlowA11yAudit
+  audit={{
+    fields: [
+      { name: 'email', label: 'Email', required: true, hasAccessibilityLabel: true },
+      { name: 'bio', placeholderOnly: true, hitHeight: 36 },
+    ],
+    respectsReducedMotion: true,
+  }}
+/>;
+```
+
+Dev-only by default (`devOnly`).
+
+---
+
+## Offline submit queue
+
+```tsx
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { useFieldFlowSubmitQueue } from 'rn-inputforge';
+
+const queue = useFieldFlowSubmitQueue({
+  key: 'signup-queue',
+  storage: AsyncStorage,
+  submit: async payload => {
+    await api.signup(payload);
+  },
+});
+
+// Instead of failing hard when offline:
+await queue.enqueue(form.values);
+// queue.pendingCount / queue.flush() / queue.clear()
+```
+
+---
+
+## 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.
+
+---
+
+## Visual system
+
+One-liner knobs on `FieldFlowThemeProvider` — easy on the eyes, fully customizable:
+
+```tsx
+<FieldFlowThemeProvider
+  theme={themePresets.soft}
+  density="comfortable"   // compact | comfortable | spacious
+  size="md"               // sm | md | lg
+  shape="rounded"         // square | rounded | pill
+  surface="soft"          // flat | elevated | soft | inset
+  focusRing="softGlow"    // solid | softGlow | underlinePulse
+  animateTheme            // soft crossfade when theme changes
+>
+  <App />
+</FieldFlowThemeProvider>
+```
+
+### Inline alert / skeleton / form header
+
+```tsx
+<FieldFlowFormHeader
+  title="Create account"
+  subtitle="A calm start — we’ll guide you through a few short steps."
+  progress={0.35}
+/>
+
+<FieldFlowInlineAlert tone="info" title="Privacy" message="We’ll never share your email." />
+
+{loading ? <FieldFlowSkeleton count={4} lastMultiline /> : <FormFields />}
+```
+
+### Info tip + helper status
+
+```tsx
+<FieldFlowInput
+  label="Tax ID"
+  infoTip="Used only for invoices. Never shown publicly."
+  helperText="Optional for personal accounts"
+  helperStatus="info"
+  ...
+/>
+```
+
+---
+
+## 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
+
+Group related fields into a themed card with optional collapse:
+
+```tsx
+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>;
+```
+
+### 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' },
+  ]}
+/>;
+```
+
+---
+
 ## Theming
 
 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' },
@@ -452,8 +1322,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
@@ -462,25 +1373,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)
-│   │   ├── FieldFlowInput/        core input + variants (outlined/filled/underline/floating)
-│   │   ├── 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
-│   │   ├── 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, Zod adapter
-│   ├── icons/                     expanded dependency-free icon set + render helper
-│   ├── utils/                     keyboard-type resolution, formatters, masks
-│   └── index.ts                   public API
-├── example/App.tsx                full usage reference
+│   ├── 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
 ```