rn-inputforge 0.5.0 → 0.5.1

package/src/components/FieldFlowInput/FieldFlowInput.tsx

@@ -10,10 +10,15 @@ import { renderFieldFlowIcon } from '../../icons/renderIcon';
 import { useFieldMotion } from '../../motion/useFieldMotion';
 import { FieldFlowAffordance } from '../FieldFlowAffordance';
 import { FieldFlowPasswordStrength } from '../FieldFlowPasswordStrength';
+import { FieldFlowInfoTip } from '../FieldFlowInfoTip';
 import {
   affordanceKindFromFieldType,
   type FieldFlowAffordanceKind,
 } from '../../utils/affordance';
+import {
+  autofillRoleFromFieldType,
+  getAutofillProps,
+} from '../../autofill/profiles';
 import { createStyles, iconColorFor, labelColorFor } from './styles';
 import type { FieldFlowInputProps } from './types';
 
@@ -58,6 +63,10 @@ export const FieldFlowInput = forwardRef<TextInput, FieldFlowInputProps>(functio
     prefix,
     suffix,
     motion = true,
+    autofill,
+    inputAccessoryViewID,
+    helperStatus,
+    infoTip,
     maxLength,
     showCharacterCount,
     onSubmitEditing,
@@ -97,6 +106,11 @@ export const FieldFlowInput = forwardRef<TextInput, FieldFlowInputProps>(functio
     [type, required, rules],
   );
 
+  const autofillProps = useMemo(() => {
+    const role = autofill ?? autofillRoleFromFieldType(type);
+    return role ? getAutofillProps(role) : undefined;
+  }, [autofill, type]);
+
   const resolvedError = errorText ?? localError;
   const state = useFieldState({
     isFocused,
@@ -271,18 +285,56 @@ export const FieldFlowInput = forwardRef<TextInput, FieldFlowInputProps>(functio
     return <View style={side === 'left' ? styles.iconSlotLeft : styles.iconSlotRight}>{affix}</View>;
   };
 
+  const focusRing = theme.appearance?.focusRing ?? 'softGlow';
+  const showFocusRing = motion && focusRing !== 'underlinePulse';
+  const resolvedHelperStatus =
+    helperStatus ??
+    (resolvedError ? 'error' : successText ? 'success' : helperText ? 'info' : 'none');
+
+  const helperIconName =
+    resolvedHelperStatus === 'success'
+      ? 'check'
+      : resolvedHelperStatus === 'error' || resolvedHelperStatus === 'warning'
+        ? 'alert'
+        : resolvedHelperStatus === 'info'
+          ? 'info'
+          : null;
+
+  const helperIconColor =
+    resolvedHelperStatus === 'success'
+      ? theme.colors.success
+      : resolvedHelperStatus === 'error'
+        ? theme.colors.error
+        : resolvedHelperStatus === 'warning'
+          ? theme.colors.warning
+          : theme.colors.info;
+
+  const helperTextStyle =
+    resolvedError
+      ? styles.errorText
+      : successText
+        ? styles.successText
+        : resolvedHelperStatus === 'warning'
+          ? styles.warningText
+          : resolvedHelperStatus === 'info' && helperText
+            ? styles.infoText
+            : styles.helperText;
+
   return (
     <View style={[styles.wrapper, containerStyle]} testID={testID}>
       {showExternalLabel ? (
-        <Text style={[styles.label, labelStyle]}>
-          {label}
-          {required ? ' *' : ''}
-        </Text>
+        <View style={styles.labelRow}>
+          <Text style={[styles.label, labelStyle]}>
+            {label}
+            {required ? ' *' : ''}
+          </Text>
+          {infoTip ? <FieldFlowInfoTip tip={infoTip} theme={themeOverride} /> : null}
+        </View>
       ) : null}
 
       <Animated.View style={fieldMotion.containerStyle}>
         <View style={[styles.inputContainer, inputContainerStyle]}>
-          {motion ? (
+          {showFocusRing ? (
             <Animated.View
               pointerEvents="none"
               style={[
@@ -290,10 +342,9 @@ export const FieldFlowInput = forwardRef<TextInput, FieldFlowInputProps>(functio
                 {
                   opacity: fieldMotion.glowOpacity.interpolate({
                     inputRange: [0, 1],
-                    outputRange: [0, 0.22],
+                    outputRange: [0, focusRing === 'solid' ? 1 : 0.22],
                   }),
                   borderColor: theme.colors.borderFocused,
-                  borderRadius: theme.spacing.borderRadius + 2,
                 },
               ]}
             />
@@ -332,12 +383,14 @@ export const FieldFlowInput = forwardRef<TextInput, FieldFlowInputProps>(functio
             placeholderTextColor={theme.colors.placeholder}
             keyboardType={fieldConfig.keyboardType}
             secureTextEntry={fieldConfig.secureTextEntry && !showPassword}
-            autoCapitalize={fieldConfig.autoCapitalize}
-            autoCorrect={fieldConfig.autoCorrect}
+            autoCapitalize={autofillProps?.autoCapitalize ?? fieldConfig.autoCapitalize}
+            autoCorrect={autofillProps?.autoCorrect ?? fieldConfig.autoCorrect}
             multiline={fieldConfig.multiline && type !== 'chat'}
             maxLength={maxLength}
             returnKeyType={fieldConfig.multiline ? 'default' : 'done'}
+            inputAccessoryViewID={inputAccessoryViewID}
             style={[styles.input, inputStyle]}
+            {...autofillProps}
             {...rest}
           />
 
@@ -383,13 +436,18 @@ export const FieldFlowInput = forwardRef<TextInput, FieldFlowInputProps>(functio
 
       {(helperText || resolvedError || successText || (showCharacterCount && maxLength)) && (
         <Animated.View style={[styles.footerRow, { opacity: fieldMotion.messageOpacity }]}>
-          <View style={{ flex: 1 }}>
+          <View style={styles.helperRow}>
+            {helperIconName && (resolvedError || successText || helperText) ? (
+              <View style={{ marginTop: 1 }}>
+                {renderFieldFlowIcon(helperIconName, helperIconColor, 13)}
+              </View>
+            ) : null}
             {resolvedError ? (
-              <Text style={[styles.errorText, errorStyle, helperStyle]}>{resolvedError}</Text>
+              <Text style={[helperTextStyle, errorStyle, helperStyle]}>{resolvedError}</Text>
             ) : successText ? (
-              <Text style={[styles.successText, helperStyle]}>{successText}</Text>
+              <Text style={[helperTextStyle, helperStyle]}>{successText}</Text>
             ) : helperText ? (
-              <Text style={[styles.helperText, helperStyle]}>{helperText}</Text>
+              <Text style={[helperTextStyle, helperStyle]}>{helperText}</Text>
             ) : null}
           </View>
           {showCharacterCount && maxLength ? (

package/src/components/FieldFlowInput/styles.ts

@@ -1,5 +1,6 @@
 import { StyleSheet } from 'react-native';
 import type { FieldFlowState, FieldFlowTheme, FieldFlowVariant } from '../../types';
+import { surfaceShadow } from '../../theme/appearance';
 
 export function borderColorFor(theme: FieldFlowTheme, state: FieldFlowState): string {
   switch (state) {
@@ -33,34 +34,51 @@ export function createStyles(
   const isUnderline = variant === 'underline';
   const isFilled = variant === 'filled';
   const isFloating = variant === 'floating';
+  const appearance = theme.appearance;
+  const surface = appearance?.surface ?? 'flat';
+  const focusRing = appearance?.focusRing ?? 'softGlow';
   const borderW = state === 'focused' ? theme.spacing.borderWidthFocused : theme.spacing.borderWidth;
+  const shadow = !isUnderline ? surfaceShadow(surface) : null;
+
+  let backgroundColor = theme.colors.background;
+  if (state === 'disabled') backgroundColor = theme.colors.backgroundDisabled;
+  else if (isFilled || surface === 'soft') backgroundColor = theme.colors.surfaceMuted ?? theme.colors.backgroundDisabled;
+  else if (surface === 'inset') backgroundColor = theme.colors.surfaceMuted ?? theme.colors.backgroundDisabled;
+  else if (surface === 'elevated') backgroundColor = theme.colors.surfaceElevated ?? theme.colors.background;
+  else if (isUnderline) backgroundColor = 'transparent';
+
+  const glowPad = focusRing === 'solid' ? 2 : focusRing === 'softGlow' ? 3 : 0;
 
   return StyleSheet.create({
     wrapper: {
       marginBottom: theme.spacing.gap * 2,
     },
+    labelRow: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: 6,
+      marginBottom: theme.spacing.gap / 1.5,
+    },
     label: {
       fontSize: theme.typography.labelFontSize,
-      marginBottom: theme.spacing.gap / 1.5,
       color: labelColorFor(theme, state),
       fontWeight: '500',
       fontFamily: theme.typography.fontFamily,
+      flexShrink: 1,
     },
     inputContainer: {
       position: 'relative',
       overflow: 'visible',
       flexDirection: 'row',
       alignItems: multiline ? 'flex-start' : 'center',
-      backgroundColor: state === 'disabled'
-        ? theme.colors.backgroundDisabled
-        : isFilled
-          ? theme.colors.backgroundDisabled
-          : isUnderline
-            ? 'transparent'
-            : theme.colors.background,
+      backgroundColor,
       borderRadius: isUnderline ? 0 : theme.spacing.borderRadius,
-      borderWidth: isUnderline ? 0 : isFilled ? 0 : borderW,
-      borderBottomWidth: isUnderline ? borderW + (state === 'focused' ? 0.5 : 0) : isFilled ? 0 : borderW,
+      borderWidth: isUnderline ? 0 : isFilled && surface !== 'inset' ? 0 : borderW,
+      borderBottomWidth: isUnderline
+        ? borderW + (state === 'focused' && focusRing === 'underlinePulse' ? 1 : state === 'focused' ? 0.5 : 0)
+        : isFilled && surface !== 'inset'
+          ? 0
+          : borderW,
       borderColor: borderColorFor(theme, state),
       paddingHorizontal: theme.spacing.paddingHorizontal,
       paddingVertical: multiline ? theme.spacing.paddingVertical : 0,
@@ -68,14 +86,16 @@ export function createStyles(
         ? undefined
         : theme.spacing.paddingVertical * 2 + theme.typography.fontSize + 6 + (isFloating ? 6 : 0),
       paddingTop: isFloating && !multiline ? theme.spacing.paddingVertical + 6 : undefined,
+      ...(shadow ?? null),
     },
     focusGlow: {
       position: 'absolute',
-      top: -3,
-      left: -3,
-      right: -3,
-      bottom: -3,
-      borderWidth: 3,
+      top: -glowPad,
+      left: -glowPad,
+      right: -glowPad,
+      bottom: -glowPad,
+      borderWidth: focusRing === 'solid' ? 2 : focusRing === 'softGlow' ? 3 : 0,
+      borderRadius: theme.spacing.borderRadius + glowPad,
     },
     affixText: {
       fontSize: theme.typography.fontSize,
@@ -86,7 +106,9 @@ export function createStyles(
     floatingLabel: {
       position: 'absolute',
       left: theme.spacing.paddingHorizontal,
-      backgroundColor: isFilled ? theme.colors.backgroundDisabled : theme.colors.background,
+      backgroundColor: isFilled || surface === 'soft' || surface === 'inset'
+        ? theme.colors.surfaceMuted ?? theme.colors.backgroundDisabled
+        : theme.colors.background,
       paddingHorizontal: 4,
       zIndex: 2,
       fontFamily: theme.typography.fontFamily,
@@ -114,8 +136,16 @@ export function createStyles(
     },
     footerRow: {
       flexDirection: 'row',
+      alignItems: 'flex-start',
       justifyContent: 'space-between',
       marginTop: theme.spacing.gap / 1.5,
+      gap: 6,
+    },
+    helperRow: {
+      flex: 1,
+      flexDirection: 'row',
+      alignItems: 'flex-start',
+      gap: 6,
     },
     helperText: {
       fontSize: theme.typography.helperFontSize,
@@ -135,6 +165,18 @@ export function createStyles(
       flexShrink: 1,
       fontFamily: theme.typography.fontFamily,
     },
+    warningText: {
+      fontSize: theme.typography.helperFontSize,
+      color: theme.colors.warning,
+      flexShrink: 1,
+      fontFamily: theme.typography.fontFamily,
+    },
+    infoText: {
+      fontSize: theme.typography.helperFontSize,
+      color: theme.colors.info,
+      flexShrink: 1,
+      fontFamily: theme.typography.fontFamily,
+    },
     charCount: {
       fontSize: theme.typography.helperFontSize,
       color: theme.colors.placeholder,

package/src/components/FieldFlowInput/types.ts

@@ -4,6 +4,7 @@ import type { FieldFlowFieldType, FieldFlowRules, FieldFlowVariant, DeepPartial,
 import type { FieldFlowIconSource } from '../../icons';
 import type { FieldFlowAffordanceChip, FieldFlowAffordanceKind } from '../../utils/affordance';
 import type { PasswordStrengthRule } from '../../utils/passwordStrength';
+import type { FieldFlowAutofillRole } from '../../autofill/profiles';
 
 export interface FieldFlowInputProps
   extends Omit<TextInputProps, 'style' | 'onChangeText' | 'onFocus' | 'onBlur' | 'onSubmitEditing'> {
@@ -89,6 +90,26 @@ export interface FieldFlowInputProps
    */
   motion?: boolean;
 
+  /**
+   * Platform autofill role (`email`, `password`, `oneTimeCode`, …).
+   * When omitted, a sensible default is inferred from `type` (email/phone/password).
+   * Pass `off` to disable. See `autofillProfiles` for screen bundles.
+   */
+  autofill?: FieldFlowAutofillRole;
+
+  /**
+   * iOS keyboard accessory id — pair with `FieldFlowKeyboardToolbar` `nativeID`.
+   */
+  inputAccessoryViewID?: string;
+
+  /**
+   * Soft status icon beside helper / success / warning copy.
+   * Error state always shows an alert icon when helperStatus is unset.
+   */
+  helperStatus?: 'info' | 'success' | 'warning' | 'error' | 'none';
+  /** Tip text — renders a `FieldFlowInfoTip` next to the label. */
+  infoTip?: string;
+
   maxLength?: number;
   showCharacterCount?: boolean;
 

package/src/components/FieldFlowKeyboardToolbar/FieldFlowKeyboardToolbar.tsx

@@ -0,0 +1,150 @@
+import React, { useMemo } from 'react';
+import {
+  InputAccessoryView,
+  Keyboard,
+  Platform,
+  Pressable,
+  StyleSheet,
+  Text,
+  View,
+  type ViewStyle,
+} from 'react-native';
+import { useFieldFlowTheme, mergeDeep } from '../../theme/ThemeProvider';
+import { defaultTheme } from '../../theme/defaultTheme';
+import type { DeepPartial, FieldFlowTheme } from '../../types';
+
+export interface FieldFlowKeyboardToolbarProps {
+  /** Must match `inputAccessoryViewID` on each TextInput (iOS). */
+  nativeID: string;
+  onPrevious?: () => void;
+  onNext?: () => void;
+  onDone?: () => void;
+  canPrevious?: boolean;
+  canNext?: boolean;
+  previousLabel?: string;
+  nextLabel?: string;
+  doneLabel?: string;
+  /** Also render a floating bar on Android (above keyboard region via absolute layout in parent). */
+  androidFloating?: boolean;
+  visible?: boolean;
+  containerStyle?: ViewStyle;
+  theme?: DeepPartial<FieldFlowTheme>;
+  testID?: string;
+}
+
+/**
+ * Prev / Next / Done accessory above the keyboard.
+ * iOS: native `InputAccessoryView`. Android: optional floating bar (`androidFloating`).
+ * Pair with `useKeyboardManager` focus helpers.
+ */
+export function FieldFlowKeyboardToolbar({
+  nativeID,
+  onPrevious,
+  onNext,
+  onDone,
+  canPrevious = true,
+  canNext = true,
+  previousLabel = 'Previous',
+  nextLabel = 'Next',
+  doneLabel = 'Done',
+  androidFloating = true,
+  visible = true,
+  containerStyle,
+  theme: themeOverride,
+  testID,
+}: FieldFlowKeyboardToolbarProps) {
+  const contextTheme = useFieldFlowTheme();
+  const theme = useMemo(
+    () => (themeOverride ? mergeDeep(contextTheme ?? defaultTheme, themeOverride) : contextTheme ?? defaultTheme),
+    [contextTheme, themeOverride],
+  );
+  const styles = useMemo(() => createStyles(theme), [theme]);
+
+  const bar = (
+    <View style={[styles.bar, containerStyle]} testID={testID}>
+      <Pressable
+        onPress={onPrevious}
+        disabled={!canPrevious || !onPrevious}
+        style={[styles.btn, (!canPrevious || !onPrevious) && styles.btnDisabled]}
+        accessibilityRole="button"
+        accessibilityLabel={previousLabel}
+      >
+        <Text style={styles.btnText}>{previousLabel}</Text>
+      </Pressable>
+      <Pressable
+        onPress={onNext}
+        disabled={!canNext || !onNext}
+        style={[styles.btn, (!canNext || !onNext) && styles.btnDisabled]}
+        accessibilityRole="button"
+        accessibilityLabel={nextLabel}
+      >
+        <Text style={styles.btnText}>{nextLabel}</Text>
+      </Pressable>
+      <View style={{ flex: 1 }} />
+      <Pressable
+        onPress={() => {
+          onDone?.();
+          Keyboard.dismiss();
+        }}
+        style={styles.done}
+        accessibilityRole="button"
+        accessibilityLabel={doneLabel}
+      >
+        <Text style={styles.doneText}>{doneLabel}</Text>
+      </Pressable>
+    </View>
+  );
+
+  if (!visible) return null;
+
+  if (Platform.OS === 'ios') {
+    return (
+      <InputAccessoryView nativeID={nativeID} backgroundColor={theme.colors.backgroundDisabled}>
+        {bar}
+      </InputAccessoryView>
+    );
+  }
+
+  if (!androidFloating) return null;
+  return <View style={styles.androidWrap}>{bar}</View>;
+}
+
+/** Stable default accessory id for FieldFlow forms. */
+export const FIELD_FLOW_KEYBOARD_TOOLBAR_ID = 'fieldflow-keyboard-toolbar';
+
+function createStyles(theme: FieldFlowTheme) {
+  return StyleSheet.create({
+    androidWrap: {
+      borderTopWidth: StyleSheet.hairlineWidth,
+      borderTopColor: theme.colors.border,
+    },
+    bar: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      paddingHorizontal: 10,
+      paddingVertical: 8,
+      backgroundColor: theme.colors.backgroundDisabled,
+      borderTopWidth: StyleSheet.hairlineWidth,
+      borderTopColor: theme.colors.border,
+      gap: 4,
+    },
+    btn: { paddingHorizontal: 10, paddingVertical: 6 },
+    btnDisabled: { opacity: 0.35 },
+    btnText: {
+      fontSize: theme.typography.helperFontSize + 1,
+      color: theme.colors.borderFocused,
+      fontWeight: '600',
+    },
+    done: {
+      paddingHorizontal: 12,
+      paddingVertical: 6,
+      borderRadius: 8,
+      backgroundColor: theme.colors.borderFocused,
+    },
+    doneText: {
+      fontSize: theme.typography.helperFontSize + 1,
+      color: '#fff',
+      fontWeight: '700',
+    },
+  });
+}

package/src/components/FieldFlowKeyboardToolbar/index.ts

@@ -0,0 +1,5 @@
+export {
+  FieldFlowKeyboardToolbar,
+  FIELD_FLOW_KEYBOARD_TOOLBAR_ID,
+} from './FieldFlowKeyboardToolbar';
+export type { FieldFlowKeyboardToolbarProps } from './FieldFlowKeyboardToolbar';

package/src/components/FieldFlowSkeleton/FieldFlowSkeleton.tsx

@@ -0,0 +1,105 @@
+import React, { useEffect, useMemo, useRef } from 'react';
+import { Animated, Easing, StyleSheet, View, type ViewStyle } from 'react-native';
+import { useFieldFlowTheme, mergeDeep } from '../../theme/ThemeProvider';
+import { defaultTheme } from '../../theme/defaultTheme';
+import { useReducedMotion } from '../../motion/useReducedMotion';
+import type { DeepPartial, FieldFlowTheme, FieldFlowVariant } from '../../types';
+
+export interface FieldFlowSkeletonProps {
+  /** How many fake fields to show. Default: 3. */
+  count?: number;
+  /** Match your form variant for realistic height. */
+  variant?: FieldFlowVariant;
+  /** Show label bars. Default: true. */
+  showLabels?: boolean;
+  /** Multiline taller block on last item. */
+  lastMultiline?: boolean;
+  containerStyle?: ViewStyle;
+  theme?: DeepPartial<FieldFlowTheme>;
+  testID?: string;
+}
+
+/**
+ * Soft shimmer placeholders while a form hydrates (draft / API).
+ */
+export function FieldFlowSkeleton({
+  count = 3,
+  variant = 'outlined',
+  showLabels = true,
+  lastMultiline = false,
+  containerStyle,
+  theme: themeOverride,
+  testID,
+}: FieldFlowSkeletonProps) {
+  const contextTheme = useFieldFlowTheme();
+  const theme = useMemo(
+    () => (themeOverride ? mergeDeep(contextTheme ?? defaultTheme, themeOverride) : contextTheme ?? defaultTheme),
+    [contextTheme, themeOverride],
+  );
+  const styles = useMemo(() => createStyles(theme, variant), [theme, variant]);
+  const reducedMotion = useReducedMotion();
+  const pulse = useRef(new Animated.Value(0.45)).current;
+
+  useEffect(() => {
+    if (reducedMotion) {
+      pulse.setValue(0.55);
+      return;
+    }
+    const loop = Animated.loop(
+      Animated.sequence([
+        Animated.timing(pulse, {
+          toValue: 0.9,
+          duration: 700,
+          easing: Easing.inOut(Easing.quad),
+          useNativeDriver: true,
+        }),
+        Animated.timing(pulse, {
+          toValue: 0.45,
+          duration: 700,
+          easing: Easing.inOut(Easing.quad),
+          useNativeDriver: true,
+        }),
+      ]),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [reducedMotion, pulse]);
+
+  return (
+    <View style={[styles.wrap, containerStyle]} testID={testID} accessibilityLabel="Loading form">
+      {Array.from({ length: count }, (_, i) => {
+        const tall = lastMultiline && i === count - 1;
+        return (
+          <View key={i} style={styles.item}>
+            {showLabels ? <Animated.View style={[styles.label, { opacity: pulse }]} /> : null}
+            <Animated.View style={[styles.field, tall && styles.fieldTall, { opacity: pulse }]} />
+          </View>
+        );
+      })}
+    </View>
+  );
+}
+
+function createStyles(theme: FieldFlowTheme, variant: FieldFlowVariant) {
+  const height =
+    theme.spacing.paddingVertical * 2 + theme.typography.fontSize + 6 + (variant === 'floating' ? 6 : 0);
+  return StyleSheet.create({
+    wrap: { marginBottom: theme.spacing.gap },
+    item: { marginBottom: theme.spacing.gap * 2 },
+    label: {
+      width: '32%',
+      height: theme.typography.labelFontSize,
+      borderRadius: 4,
+      backgroundColor: theme.colors.backgroundDisabled,
+      marginBottom: theme.spacing.gap,
+    },
+    field: {
+      height,
+      borderRadius: theme.spacing.borderRadius,
+      backgroundColor: theme.colors.backgroundDisabled,
+      borderWidth: StyleSheet.hairlineWidth,
+      borderColor: theme.colors.border,
+    },
+    fieldTall: { height: 88 },
+  });
+}

package/src/components/FieldFlowSkeleton/index.ts

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

package/src/components/KeyboardAwareFormWrapper/KeyboardAwareFormWrapper.tsx

@@ -1,9 +1,10 @@
-import React from 'react';
+import React, { useRef } from 'react';
 import { KeyboardAvoidingView, Platform, ScrollView, StyleSheet, ViewStyle } from 'react-native';
 import type { UseKeyboardManagerResult } from '../../hooks/useKeyboardManager';
 
 export interface KeyboardAwareFormWrapperProps {
-  keyboardManager: Pick<UseKeyboardManagerResult, 'scrollViewRef'>;
+  /** Optional — omit when you only need keyboard-avoiding scroll without Next/Done chaining. */
+  keyboardManager?: Pick<UseKeyboardManagerResult, 'scrollViewRef'>;
   children: React.ReactNode;
   contentContainerStyle?: ViewStyle;
   style?: ViewStyle;
@@ -13,7 +14,7 @@ export interface KeyboardAwareFormWrapperProps {
  * Wrap your form fields in this instead of a plain ScrollView. It automatically
  * keeps the focused field visible above the keyboard and animates smoothly on
  * both iOS and Android; pass it the same `keyboardManager` you got from
- * `useKeyboardManager()`.
+ * `useKeyboardManager()` when you want auto-scroll + Next/Done focus.
  */
 export function KeyboardAwareFormWrapper({
   keyboardManager,
@@ -21,6 +22,9 @@ export function KeyboardAwareFormWrapper({
   contentContainerStyle,
   style,
 }: KeyboardAwareFormWrapperProps) {
+  const fallbackScrollRef = useRef<ScrollView>(null);
+  const scrollRef = keyboardManager?.scrollViewRef ?? fallbackScrollRef;
+
   return (
     <KeyboardAvoidingView
       style={[styles.flex, style]}
@@ -28,7 +32,7 @@ export function KeyboardAwareFormWrapper({
       keyboardVerticalOffset={Platform.OS === 'ios' ? 64 : 0}
     >
       <ScrollView
-        ref={keyboardManager.scrollViewRef}
+        ref={scrollRef}
         keyboardShouldPersistTaps="handled"
         contentContainerStyle={[styles.content, contentContainerStyle]}
         showsVerticalScrollIndicator={false}

package/src/hooks/index.ts

@@ -44,3 +44,20 @@ export type {
   UseFieldFlowDirtyGuardOptions,
   UseFieldFlowDirtyGuardResult,
 } from './useFieldFlowDirtyGuard';
+
+export { useFieldFlowCompleteness } from './useFieldFlowCompleteness';
+export type {
+  UseFieldFlowCompletenessOptions,
+  UseFieldFlowCompletenessResult,
+} from './useFieldFlowCompleteness';
+
+export { useFieldFlowSubmitQueue } from './useFieldFlowSubmitQueue';
+export type {
+  FieldFlowSubmitJob,
+  FieldFlowSubmitQueueStorage,
+  UseFieldFlowSubmitQueueOptions,
+  UseFieldFlowSubmitQueueResult,
+} from './useFieldFlowSubmitQueue';
+
+export { useSmartPaste } from './useSmartPaste';
+export type { UseSmartPasteOptions } from './useSmartPaste';