feat(core): implement advanced keyboard management and fix monorepo b… (#3)

* feat(core): implement advanced keyboard management and fix monorepo bundling

This commit introduces several new props to FieldForm (autoScroll, chainEnabled, autoReturnKeyType, dismissKeyboardOnTap, etc.) and resolves bundling issues in the monorepo showcase app by hoisting runtime polyfills to the project root.

* feat: add field skipping, Reanimated keyboard support, and optional submit-on-done behavior to FieldForm

* docs: update README with performance details, default padding, and new field skip/submit props

Author: SyedSohaib456

README.md

@@ -161,6 +161,9 @@ At the same time, every `FieldInput` registers itself into an ordered focus chai
 
 Nothing about this requires native modules. It is entirely JS-side and works on Expo, bare RN, and the New Architecture.
 
+### ⚡ 60fps Native Performance
+**FieldFlow** strictly requires [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/) as a peer dependency. By mandating Reanimated, the library delegates all keyboard layout tracking to a high-performance C++ worklet via `useAnimatedKeyboard()`. This completely bypasses the JavaScript bridge during animations, resulting in maximum UI thread performance (smooth 60fps) during heavy keyboard pan gestures that would otherwise stutter on the JS thread.
+
 ---
 
 ## API
@@ -170,9 +173,10 @@ Nothing about this requires native modules. It is entirely JS-side and works on
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `onSubmit` | `() => void` | — | Called when the last field is submitted |
-| `extraScrollPadding` | `number` | `100` | Space between the active field and the keyboard top edge |
+| `extraScrollPadding` | `number` | `40` | Space between the active field and the keyboard top edge |
 | `scrollable` | `boolean` | `true` | Wrap children in a managed ScrollView |
 | `avoidKeyboard` | `boolean` | `true` | Enable the animated keyboard spacer |
+| `submitOnLastFieldDone` | `boolean` | `false` | Submit the whole form / call `onSubmit` when "Done" is pressed on the final field |
 | `style` | `ViewStyle` | — | Container style |
 | `scrollViewProps` | `ScrollViewProps` | — | Forwarded to the internal ScrollView |
 | `onKeyboardShow` | `(height: number) => void` | — | Called when keyboard appears |
@@ -184,7 +188,7 @@ Accepts every `TextInput` prop, plus:
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `shouldIgnoreChain` | `boolean` | `false` | Exclude this field from the focus chain |
+| `skip` | `boolean` | `false` | Exclude this field from the auto-focus chain entirely |
 | `nextRef` | `RefObject<TextInput>` | — | Override: focus this ref instead of the auto-detected next field |
 | `onFormSubmit` | `() => void` | — | Override: called when this field is the last and Done is tapped |
 
@@ -304,7 +308,7 @@ const MyInput = forwardRef<TextInput, MyInputProps>((props, ref) => (
 <summary><b>Can I skip a field in the chain?</b></summary>
 <br/>
 
-Yes. Add `shouldIgnoreChain` to any `FieldInput` and the focus chain skips over it as if it doesn't exist. The field is still fully functional — it just doesn't participate in Next/Done handling.
+Yes. Add `skip={true}` to any `FieldInput` and the focus chain skips over it dynamically. The field is still fully functional — it just doesn't participate in Next/Done handling.
 </details>
 
 <details>

example/app/(tabs)/advanced.tsx

@@ -169,12 +169,12 @@ export default function AdvancedScreen() {
             icon="play-outline"
             label="Start here"
             placeholder='Press "Next" on keyboard →'
-            nextRef={customTargetRef}
           />
           <StyledInput
             icon="play-skip-forward-outline"
             label="Skipped"
             placeholder="This field is skipped"
+            skip={true}
           />
           <View>
             <View style={styles.targetLabelRow}>

packages/react-native-fieldflow/src/FieldForm.tsx

@@ -23,6 +23,45 @@ import {
   type TextInput,
 } from 'react-native';
 
+let AnimatedReanimatedView: any;
+let useAnimatedKeyboard: any;
+let useAnimatedStyle: any;
+let isReanimatedAvailable = false;
+
+try {
+  const rea = require('react-native-reanimated');
+  // Handle different ESM/CJS export artifacts in React Native versions
+  AnimatedReanimatedView = rea.default?.View || rea.Animated?.View || rea.View;
+  useAnimatedKeyboard = rea.useAnimatedKeyboard;
+  useAnimatedStyle = rea.useAnimatedStyle;
+  if (AnimatedReanimatedView && useAnimatedKeyboard && useAnimatedStyle) {
+    isReanimatedAvailable = true;
+  }
+} catch (e) {
+  // gracefully degrade to Animated.timing if not found
+}
+
+const ReanimatedSpacer = ({
+  avoidKeyboard,
+  offset,
+  extraPad,
+}: {
+  avoidKeyboard: boolean;
+  offset: number;
+  extraPad: number;
+}) => {
+  // We can safely call hooks here because this component is only rendered if isReanimatedAvailable = true
+  const keyboard = useAnimatedKeyboard();
+  const animatedStyle = useAnimatedStyle(() => {
+    const kHeight = avoidKeyboard ? keyboard.height.value : 0;
+    const finalHeight = Math.max(kHeight + offset, 0);
+    return { height: finalHeight + extraPad };
+  }, [avoidKeyboard, offset, extraPad]);
+  
+  const AnimatedView = AnimatedReanimatedView;
+  return <AnimatedView style={animatedStyle} />;
+};
+
 import { FieldFlowContext } from './context';
 import type {
   FieldFormContextValue,
@@ -31,7 +70,7 @@ import type {
   KeyboardPlatformOs,
 } from './types';
 
-const defaultExtraScrollPadding = 10;
+const defaultExtraScrollPadding = 50;
 
 function resolveKeyboardVerticalOffset(
   value: FieldFormProps['keyboardVerticalOffset'],
@@ -76,10 +115,11 @@ export const FieldForm = forwardRef<FieldFormHandle, FieldFormProps>((props, ref
       chainEnabled = true,
       autoReturnKeyType = true,
       dismissKeyboardOnTap = false,
+      submitOnLastFieldDone = false,
       scrollViewRef: scrollViewRefProp,
     } = props;
 
-    const fieldsRef = useRef<React.MutableRefObject<TextInput | null>[]>([]);
+    const fieldsRef = useRef<{ ref: React.MutableRefObject<TextInput | null>; skip?: boolean }[]>([]);
     const internalScrollRef = useRef<ScrollView | null>(null);
 
     const setMergedScrollRef = useCallback(
@@ -95,22 +135,40 @@ export const FieldForm = forwardRef<FieldFormHandle, FieldFormProps>((props, ref
       [scrollViewRefProp],
     );
 
-    const register = useCallback((inputRef: React.MutableRefObject<TextInput | null>): number => {
+    const register = useCallback((inputRef: React.MutableRefObject<TextInput | null>, skip?: boolean): number => {
       const fields = fieldsRef.current;
-      if (!fields.includes(inputRef)) {
-        fields.push(inputRef);
+      const existingIdx = fields.findIndex(f => f.ref === inputRef);
+      if (existingIdx === -1) {
+        fields.push({ ref: inputRef, skip });
+        return fields.length - 1;
       }
-      return fields.indexOf(inputRef);
+      return existingIdx;
     }, []);
 
     const unregister = useCallback((inputRef: React.MutableRefObject<TextInput | null>) => {
       const fields = fieldsRef.current;
-      const idx = fields.indexOf(inputRef);
+      const idx = fields.findIndex(f => f.ref === inputRef);
       if (idx > -1) fields.splice(idx, 1);
     }, []);
 
+    const updateField = useCallback((inputRef: React.MutableRefObject<TextInput | null>, skip?: boolean) => {
+      const fields = fieldsRef.current;
+      const idx = fields.findIndex(f => f.ref === inputRef);
+      if (idx > -1) {
+        fields[idx].skip = skip;
+      }
+    }, []);
+
     const count = useCallback(() => fieldsRef.current.length, []);
 
+    const hasNext = useCallback((currentIndex: number) => {
+      const fields = fieldsRef.current;
+      for (let i = currentIndex + 1; i < fields.length; i++) {
+        if (!fields[i].skip) return true;
+      }
+      return false;
+    }, []);
+
     const scrollInputIntoView = useCallback(
       (input: TextInput | null, padding?: number) => {
         const scroll = internalScrollRef.current;
@@ -133,10 +191,18 @@ export const FieldForm = forwardRef<FieldFormHandle, FieldFormProps>((props, ref
     const focusNext = useCallback(
       (currentIndex: number) => {
         const fields = fieldsRef.current;
-        const next = fields[currentIndex + 1];
-        if (next?.current) {
-          next.current.focus();
-          scrollInputIntoView(next.current);
+        let nextField = null;
+        
+        for (let i = currentIndex + 1; i < fields.length; i++) {
+          if (!fields[i].skip) {
+            nextField = fields[i].ref;
+            break;
+          }
+        }
+        
+        if (nextField?.current) {
+          nextField.current.focus();
+          scrollInputIntoView(nextField.current);
         } else if (dismissKeyboardOnFocusPastLast) {
           Keyboard.dismiss();
         }
@@ -186,7 +252,7 @@ export const FieldForm = forwardRef<FieldFormHandle, FieldFormProps>((props, ref
         const offset = resolveKeyboardVerticalOffset(keyboardVerticalOffset);
         const finalHeight = Math.max(h + offset, 0);
 
-        if (avoidKeyboard) {
+        if (avoidKeyboard && !isReanimatedAvailable) {
           Animated.timing(animatedMargin, {
             toValue: finalHeight,
             duration: e.duration || 250,
@@ -198,12 +264,14 @@ export const FieldForm = forwardRef<FieldFormHandle, FieldFormProps>((props, ref
       });
 
       const hideSub = Keyboard.addListener(hideEvent, e => {
-        Animated.timing(animatedMargin, {
-          toValue: 0,
-          duration: e?.duration || 250,
-          easing: Easing.out(Easing.quad),
-          useNativeDriver: false,
-        }).start();
+        if (!isReanimatedAvailable) {
+          Animated.timing(animatedMargin, {
+            toValue: 0,
+            duration: e?.duration || 250,
+            easing: Easing.out(Easing.quad),
+            useNativeDriver: false,
+          }).start();
+        }
         onKeyboardHide?.();
       });
 
@@ -224,24 +292,30 @@ export const FieldForm = forwardRef<FieldFormHandle, FieldFormProps>((props, ref
       (): FieldFormContextValue => ({
         register,
         unregister,
+        updateField,
         focusNext,
         scrollInputIntoView,
         submitForm,
         count,
+        hasNext,
         autoScroll,
         chainEnabled,
         autoReturnKeyType,
+        submitOnLastFieldDone,
       }),
       [
         register,
         unregister,
+        updateField,
         focusNext,
         scrollInputIntoView,
         submitForm,
         count,
+        hasNext,
         autoScroll,
         chainEnabled,
         autoReturnKeyType,
+        submitOnLastFieldDone,
       ],
     );
 
@@ -277,10 +351,21 @@ export const FieldForm = forwardRef<FieldFormHandle, FieldFormProps>((props, ref
         showsVerticalScrollIndicator,
         style: scrollStyleFromProps,
         contentContainerStyle: mergedContentContainerStyle,
+        automaticallyAdjustKeyboardInsets: Platform.OS === 'ios' ? avoidKeyboard : undefined,
         children: (
           <>
             {children}
-            <Animated.View style={{ height: Animated.add(extraScrollPadding, animatedMargin) }} />
+            {Platform.OS === 'ios' && avoidKeyboard ? (
+              <View style={{ height: extraScrollPadding }} />
+            ) : isReanimatedAvailable ? (
+              <ReanimatedSpacer
+                avoidKeyboard={avoidKeyboard}
+                offset={kavOffset}
+                extraPad={typeof extraScrollPadding === 'number' ? extraScrollPadding : 0}
+              />
+            ) : (
+              <Animated.View style={{ height: Animated.add(extraScrollPadding, animatedMargin) }} />
+            )}
           </>
         ),
         ...scrollRest,

packages/react-native-fieldflow/src/FieldInput.tsx

@@ -1,6 +1,6 @@
 import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useRef } from 'react';
 import type { NativeSyntheticEvent, TextInputSubmitEditingEventData } from 'react-native';
-import { TextInput } from 'react-native';
+import { Keyboard, TextInput } from 'react-native';
 
 import { useFieldFlow } from './context';
 import type { FieldInputProps } from './types';
@@ -14,6 +14,7 @@ export const FieldInput = forwardRef<TextInput, FieldInputProps>((props, forward
     returnKeyType,
     registerWithForm = true,
     blurOnSubmit: blurOnSubmitProp,
+    skip,
     ...rest
   } = props;
 
@@ -26,14 +27,21 @@ export const FieldInput = forwardRef<TextInput, FieldInputProps>((props, forward
     if (!registerWithForm || !ctx) {
       return undefined;
     }
-    indexRef.current = ctx.register(internalRef);
+    indexRef.current = ctx.register(internalRef, skip);
     return () => ctx.unregister(internalRef);
-  }, [ctx, registerWithForm]);
+  }, [ctx, registerWithForm, skip]);
+
+  useEffect(() => {
+    if (registerWithForm && ctx) {
+      ctx.updateField(internalRef, skip);
+    }
+  }, [skip, ctx, registerWithForm]);
 
   const isLast = useCallback((): boolean => {
     if (!ctx) return true;
     const idx = chainIndex ?? indexRef.current;
-    return idx === ctx.count() - 1;
+    if (idx === -1) return true;
+    return !ctx.hasNext(idx);
   }, [ctx, chainIndex]);
 
   const handleSubmitEditing = useCallback(
@@ -46,8 +54,12 @@ export const FieldInput = forwardRef<TextInput, FieldInputProps>((props, forward
       if (nextRef?.current) {
         nextRef.current.focus();
       } else if (isLast()) {
-        onFormSubmit?.();
-        ctx.submitForm();
+        if (ctx.submitOnLastFieldDone) {
+          onFormSubmit?.();
+          ctx.submitForm();
+        } else {
+          Keyboard.dismiss();
+        }
       } else if (ctx.chainEnabled) {
         ctx.focusNext(idx);
       }

packages/react-native-fieldflow/src/types.ts

@@ -11,17 +11,20 @@ import type {
 
 /** Public context API for field registration and chained focus (used by `KeyboardInput`). */
 export interface FieldFormContextValue {
-  register: (inputRef: MutableRefObject<TextInput | null>) => number;
+  register: (inputRef: MutableRefObject<TextInput | null>, skip?: boolean) => number;
   unregister: (inputRef: MutableRefObject<TextInput | null>) => void;
+  updateField: (inputRef: MutableRefObject<TextInput | null>, skip?: boolean) => void;
   focusNext: (currentIndex: number) => void;
   /** Scrolls the form scroll view to ensure the given input is visible above the keyboard. */
   scrollInputIntoView: (input: TextInput | null, padding?: number) => void;
   submitForm: () => void;
   count: () => number;
+  hasNext: (currentIndex: number) => boolean;
   /** @internal settings from FieldForm */
   autoScroll: boolean;
   chainEnabled: boolean;
   autoReturnKeyType: boolean;
+  submitOnLastFieldDone: boolean;
 }
 
 /** Imperative API when `KeyboardForm` is used with `ref`. */
@@ -107,6 +110,8 @@ export interface FieldFormProps {
   dismissKeyboardOnSubmit?: boolean;
   /** When moving past the last field via `focusNext`. @default true */
   dismissKeyboardOnFocusPastLast?: boolean;
+  /** Submit the whole form / call `onSubmit` when the "Done" key is pressed on the last field. @default false */
+  submitOnLastFieldDone?: boolean;
 
   /**
    * Use your own ref for the scroll view instead of an internal one
@@ -124,6 +129,8 @@ export interface FieldInputProps extends TextInputProps {
   nextRef?: MutableRefObject<TextInput | null>;
   /** Set false to use `KeyboardInput` outside a `KeyboardForm`. @default true */
   registerWithForm?: boolean;
+  /** Skip this field during standard keyboard "Next" navigation. @default false */
+  skip?: boolean;
 }
 
 export type FieldInputSubmitEditingEvent =