react-native-keyboard-controller 1.21.0-beta.2 → 1.21.0

package/lib/typescript/components/KeyboardChatScrollView/useChatKeyboard/helpers.d.ts

@@ -0,0 +1,132 @@
+import type { KeyboardLiftBehavior } from "./types";
+/**
+ * Map the current keyboard height to an effective height that accounts for a
+ * fixed offset (e.g. Bottom safe-area or tab-bar height)..
+ *
+ * @param height - Current keyboard height.
+ * @param targetKeyboardHeight - Full target keyboard height (captured on keyboard open).
+ * @param offset - Fixed distance between the scroll-view bottom and the screen bottom.
+ * @returns Effective height after subtracting the offset proportionally.
+ * @example
+ * ```ts
+ * getEffectiveHeight(300, 300, 50); // 250
+ * getEffectiveHeight(150, 300, 50); // 125
+ * ```
+ */
+export declare const getEffectiveHeight: (height: number, targetKeyboardHeight: number, offset: number) => number;
+/**
+ * Check whether the scroll view is at the end of its content.
+ *
+ * For non-inverted lists the "end" is the bottom of the content.
+ * For inverted lists the "end" is the top (scroll offset near 0),
+ * because that is where the latest messages are displayed.
+ *
+ * @param scrollOffset - Current vertical scroll offset.
+ * @param layoutHeight - Visible height of the scroll view.
+ * @param contentHeight - Total height of the scrollable content.
+ * @param inverted - Whether the list is inverted.
+ * @returns `true` if the scroll position is within the threshold of the content end.
+ * @example
+ * ```ts
+ * const atEnd = isScrollAtEnd(100, 800, 920); // true (100 + 800 >= 920 - 20)
+ * const atEndInverted = isScrollAtEnd(5, 800, 2000, true); // true (5 <= 20)
+ * ```
+ */
+export declare const isScrollAtEnd: (scrollOffset: number, layoutHeight: number, contentHeight: number, inverted?: boolean) => boolean;
+/**
+ * Decide whether content should be shifted based on the keyboard lift behavior.
+ *
+ * @param behavior - The configured keyboard lift behavior.
+ * @param isAtEnd - Whether the scroll view is currently at the end.
+ * @returns `true` if content should be shifted.
+ * @example
+ * ```ts
+ * shouldShiftContent("always", false); // true
+ * shouldShiftContent("whenAtEnd", false); // false
+ * ```
+ */
+export declare const shouldShiftContent: (behavior: KeyboardLiftBehavior, isAtEnd: boolean) => boolean;
+/**
+ * Compute the fraction of minimum padding space currently visible in the viewport (0–1).
+ *
+ * The minimum padding space lives in the scroll view's contentInset, NOT in the
+ * content itself.  So `contentHeight` (from onContentSizeChange / scroll
+ * events) does **not** include it.  The visible portion is how far the
+ * viewport extends past the content boundary into the inset area.
+ *
+ * For non-inverted lists the padding is in contentInset.bottom.
+ * For inverted lists the padding is in contentInset.top (negative scroll).
+ *
+ * @param scrollOffset - Current vertical scroll offset.
+ * @param layoutHeight - Visible height of the scroll view.
+ * @param contentHeight - Height of the scroll content (excludes insets).
+ * @param blankSpace - Size of the minimum padding inset area.
+ * @param inverted - Whether the list is inverted.
+ * @returns A value between 0 (padding fully off-screen) and 1 (padding fully visible).
+ * @example
+ * ```ts
+ * // Non-inverted: contentHeight=1500, layout=800, blankSpace=300
+ * getVisibleMinimumPaddingFraction(1500, 800, 1500, 300, false); // 1   (at end, viewport past content)
+ * getVisibleMinimumPaddingFraction(850, 800, 1500, 300, false);  // 0.5 (half padding visible)
+ * getVisibleMinimumPaddingFraction(700, 800, 1500, 300, false);  // 0   (padding off-screen)
+ * ```
+ */
+export declare const getVisibleMinimumPaddingFraction: (scrollOffset: number, layoutHeight: number, contentHeight: number, blankSpace: number, inverted: boolean) => number;
+/**
+ * Compute how much of the minimum content padding absorbs the keyboard + extraContentPadding.
+ *
+ * @param blankSpace - Minimum inset floor.
+ * @param extraContentPadding - Extra content padding from external elements.
+ * @returns The portion of blankSpace that absorbs keyboard displacement.
+ * @example
+ * ```ts
+ * getMinimumPaddingAbsorbed(500, 20); // 480
+ * getMinimumPaddingAbsorbed(0, 20);   // 0
+ * ```
+ */
+export declare const getMinimumPaddingAbsorbed: (blankSpace: number, extraContentPadding: number) => number;
+/**
+ * Compute the effective scroll displacement after minimum padding absorption.
+ *
+ * @param rawEffective - Raw effective keyboard height.
+ * @param minimumPaddingAbsorbed - Amount absorbed by minimum content padding.
+ * @returns The scroll displacement after subtracting the absorbed portion.
+ * @example
+ * ```ts
+ * getScrollEffective(300, 200); // 100
+ * getScrollEffective(300, 400); // 0
+ * ```
+ */
+export declare const getScrollEffective: (rawEffective: number, minimumPaddingAbsorbed: number) => number;
+/**
+ * Compute the clamped scroll target for non-inverted lists.
+ *
+ * @param offsetBeforeScroll - Scroll position before keyboard appeared.
+ * @param keyboardHeight - Current keyboard height (used for scroll displacement).
+ * @param contentHeight - Total height of the scrollable content.
+ * @param layoutHeight - Visible height of the scroll view.
+ * @param totalPaddingForMaxScroll - Total padding to use for maxScroll calculation. When provided, used instead of keyboardHeight for the scrollable range. Defaults to keyboardHeight.
+ * @returns Clamped scroll target between 0 and maxScroll.
+ * @example
+ * ```ts
+ * clampedScrollTarget(100, 300, 1000, 800); // 400
+ * clampedScrollTarget(100, 100, 1000, 800, 500); // 200, maxScroll uses 500
+ * ```
+ */
+export declare const clampedScrollTarget: (offsetBeforeScroll: number, keyboardHeight: number, contentHeight: number, layoutHeight: number, totalPaddingForMaxScroll?: number) => number;
+/**
+ * Compute contentOffset.y for iOS lists.
+ *
+ * @param relativeScroll - Scroll position relative to current inset.
+ * @param keyboardHeight - Target keyboard height (used for scroll displacement).
+ * @param contentHeight - Total height of the scrollable content.
+ * @param layoutHeight - Visible height of the scroll view.
+ * @param inverted - Whether the list is inverted.
+ * @param totalPaddingForMaxScroll - Total padding to use for maxScroll calculation. When provided, used instead of keyboardHeight for the scrollable range. Defaults to keyboardHeight.
+ * @returns The absolute contentOffset.y to set.
+ * @example
+ * ```ts
+ * computeIOSContentOffset(100, 300, 1000, 800, false); // 400
+ * ```
+ */
+export declare const computeIOSContentOffset: (relativeScroll: number, keyboardHeight: number, contentHeight: number, layoutHeight: number, inverted: boolean, totalPaddingForMaxScroll?: number) => number;

package/lib/typescript/components/KeyboardChatScrollView/useChatKeyboard/index.d.ts

@@ -0,0 +1,18 @@
+import type { UseChatKeyboardOptions, UseChatKeyboardReturn } from "./types";
+import type { AnimatedRef } from "react-native-reanimated";
+import type Reanimated from "react-native-reanimated";
+/**
+ * Hook that manages keyboard-driven scrolling for chat-style scroll views.
+ * Calculates padding (extra scrollable space) and content shift values,
+ * using per-frame scrollTo updates (Android and other platforms).
+ *
+ * @param scrollViewRef - Animated ref to the scroll view.
+ * @param options - Configuration for inverted and keyboardLiftBehavior.
+ * @returns Shared values for padding and contentOffsetY (always `undefined`).
+ * @example
+ * ```tsx
+ * const { padding } = useChatKeyboard(ref, { inverted: false, keyboardLiftBehavior: "always" });
+ * ```
+ */
+declare function useChatKeyboard(scrollViewRef: AnimatedRef<Reanimated.ScrollView>, options: UseChatKeyboardOptions): UseChatKeyboardReturn;
+export { useChatKeyboard };

package/lib/typescript/components/KeyboardChatScrollView/useChatKeyboard/index.ios.d.ts

@@ -0,0 +1,21 @@
+import type { UseChatKeyboardOptions, UseChatKeyboardReturn } from "./types";
+import type { AnimatedRef } from "react-native-reanimated";
+import type Reanimated from "react-native-reanimated";
+/**
+ * Hook that manages keyboard-driven scrolling for chat-style scroll views.
+ * Calculates padding (extra scrollable space) and content shift values,
+ * using iOS-specific strategy (contentOffset set once in onStart).
+ *
+ * @param scrollViewRef - Animated ref to the scroll view.
+ * @param options - Configuration for inverted and keyboardLiftBehavior.
+ * @returns Shared values for padding and contentOffsetY.
+ * @example
+ * ```tsx
+ * const { padding, contentOffsetY } = useChatKeyboard(ref, {
+ *   inverted: false,
+ *   keyboardLiftBehavior: "always",
+ * });
+ * ```
+ */
+declare function useChatKeyboard(scrollViewRef: AnimatedRef<Reanimated.ScrollView>, options: UseChatKeyboardOptions): UseChatKeyboardReturn;
+export { useChatKeyboard };

package/lib/typescript/components/KeyboardChatScrollView/useChatKeyboard/types.d.ts

@@ -0,0 +1,37 @@
+import type { LayoutChangeEvent } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
+type KeyboardLiftBehavior = "always" | "whenAtEnd" | "persistent" | "never";
+type UseChatKeyboardOptions = {
+    inverted: boolean;
+    keyboardLiftBehavior: KeyboardLiftBehavior;
+    freeze: boolean;
+    offset: number;
+    blankSpace: SharedValue<number>;
+    /** Extra content padding shared value — needed on iOS to correctly clamp contentOffset. */
+    extraContentPadding: SharedValue<number>;
+};
+type UseChatKeyboardReturn = {
+    /** Extra scrollable space (= keyboard height). Used as contentInset on iOS, contentInsetBottom/contentInsetTop on Android. */
+    padding: SharedValue<number>;
+    /** Raw keyboard height updated every frame in onMove. Used to force Reanimated commits on Fabric. */
+    currentHeight: SharedValue<number>;
+    /** Absolute Y content offset for iOS (set once in onStart). `undefined` on Android. */
+    contentOffsetY: SharedValue<number> | undefined;
+    /** Current vertical scroll offset. */
+    scroll: SharedValue<number>;
+    /** Visible viewport dimensions. */
+    layout: SharedValue<{
+        width: number;
+        height: number;
+    }>;
+    /** Total content dimensions. */
+    size: SharedValue<{
+        width: number;
+        height: number;
+    }>;
+    /** Callback to attach to ScrollView's onLayout prop to capture initial viewport dimensions. */
+    onLayout: (e: LayoutChangeEvent) => void;
+    /** Callback to attach to ScrollView's onContentSizeChange prop to capture initial content dimensions. */
+    onContentSizeChange: (w: number, h: number) => void;
+};
+export type { KeyboardLiftBehavior, UseChatKeyboardOptions, UseChatKeyboardReturn, };

package/lib/typescript/components/KeyboardChatScrollView/useExtraContentPadding/index.d.ts

@@ -0,0 +1,43 @@
+import type { KeyboardLiftBehavior } from "../useChatKeyboard/types";
+import type { AnimatedRef, SharedValue } from "react-native-reanimated";
+import type Reanimated from "react-native-reanimated";
+type UseExtraContentPaddingOptions = {
+    scrollViewRef: AnimatedRef<Reanimated.ScrollView>;
+    extraContentPadding: SharedValue<number>;
+    /** Keyboard-only padding from useChatKeyboard — used to compute total padding for clamping. */
+    keyboardPadding: SharedValue<number>;
+    /** Minimum inset floor — used to absorb keyboard and extraContentPadding changes. */
+    blankSpace: SharedValue<number>;
+    /** Current vertical scroll offset. */
+    scroll: SharedValue<number>;
+    /** Visible viewport dimensions. */
+    layout: SharedValue<{
+        width: number;
+        height: number;
+    }>;
+    /** Total content dimensions. */
+    size: SharedValue<{
+        width: number;
+        height: number;
+    }>;
+    inverted: boolean;
+    keyboardLiftBehavior: KeyboardLiftBehavior;
+    freeze: boolean;
+};
+/**
+ * Hook that reacts to `extraContentPadding` changes and conditionally
+ * adjusts the scroll position using `scrollTo` on both iOS and Android.
+ *
+ * Padding extension (scrollable range) is handled externally via a
+ * `useDerivedValue` that sums keyboard padding + extra content padding.
+ * This hook only handles the scroll correction.
+ *
+ * @param options - Configuration and shared values.
+ * @example
+ * ```tsx
+ * useExtraContentPadding({ scrollViewRef, extraContentPadding, ... });
+ * ```
+ */
+declare function useExtraContentPadding(options: UseExtraContentPaddingOptions): void;
+export { useExtraContentPadding };
+export type { UseExtraContentPaddingOptions };

package/lib/typescript/components/KeyboardToolbar/index.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import { RCTKeyboardToolbarGroupView } from "../../bindings";
 import { colors } from "./colors";
 import { Background, Content, Done, Next, Prev } from "./compound/components";
 import type { KeyboardToolbarProps } from "./types";
@@ -22,6 +23,7 @@ declare const KeyboardToolbar: React.FC<KeyboardToolbarProps> & {
     Prev: typeof Prev;
     Next: typeof Next;
     Done: typeof Done;
+    Group: typeof RCTKeyboardToolbarGroupView;
 };
 export { colors as DefaultKeyboardToolbarTheme, KeyboardToolbarProps };
 export default KeyboardToolbar;

package/lib/typescript/components/ScrollViewWithBottomPadding/index.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
 import Reanimated from "react-native-reanimated";
-import type { ScrollViewProps, StyleProp, ViewStyle } from "react-native";
+import type { ScrollViewProps } from "react-native";
 import type { SharedValue } from "react-native-reanimated";
 type AnimatedScrollViewProps = React.ComponentProps<typeof Reanimated.ScrollView>;
 export type AnimatedScrollViewComponent = React.ForwardRefExoticComponent<AnimatedScrollViewProps & React.RefAttributes<Reanimated.ScrollView>>;
@@ -9,9 +9,10 @@ declare const ScrollViewWithBottomPadding: React.ForwardRefExoticComponent<{
     children?: React.ReactNode;
     inverted?: boolean;
     bottomPadding: SharedValue<number>;
-    /** Absolute Y content offset (iOS only, for ChatKit). */
+    /** Padding for scroll indicator insets (excludes blankSpace). Falls back to bottomPadding when not provided. */
+    scrollIndicatorPadding?: SharedValue<number>;
+    /** Absolute Y content offset (iOS only, for KeyboardChatScrollView). */
     contentOffsetY?: SharedValue<number>;
-    /** Style applied to the container wrapper (Android only, for ChatKit translateY). */
-    containerStyle?: StyleProp<ViewStyle>;
+    applyWorkaroundForContentInsetHitTestBug?: boolean;
 } & ScrollViewProps & React.RefAttributes<Reanimated.ScrollView>>;
 export default ScrollViewWithBottomPadding;

package/lib/typescript/components/hooks/useScrollState.d.ts

@@ -1,3 +1,4 @@
+import type { LayoutChangeEvent } from "react-native";
 import type { AnimatedRef } from "react-native-reanimated";
 import type Reanimated from "react-native-reanimated";
 declare const useScrollState: (ref: AnimatedRef<Reanimated.ScrollView>) => {
@@ -10,5 +11,7 @@ declare const useScrollState: (ref: AnimatedRef<Reanimated.ScrollView>) => {
         width: number;
         height: number;
     }>;
+    onLayout: (e: LayoutChangeEvent) => void;
+    onContentSizeChange: (w: number, h: number) => void;
 };
 export default useScrollState;

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

@@ -2,9 +2,9 @@ export { default as KeyboardAvoidingView } from "./KeyboardAvoidingView";
 export { default as KeyboardStickyView } from "./KeyboardStickyView";
 export { default as KeyboardAwareScrollView } from "./KeyboardAwareScrollView";
 export { default as KeyboardToolbar, DefaultKeyboardToolbarTheme, } from "./KeyboardToolbar";
-export { default as ChatKit } from "./ChatKit";
+export { default as KeyboardChatScrollView } from "./KeyboardChatScrollView";
 export type { KeyboardAvoidingViewProps } from "./KeyboardAvoidingView";
 export type { KeyboardStickyViewProps } from "./KeyboardStickyView";
 export type { KeyboardAwareScrollViewProps, KeyboardAwareScrollViewRef, } from "./KeyboardAwareScrollView";
 export type { KeyboardToolbarProps } from "./KeyboardToolbar";
-export type { ChatKitScrollViewProps } from "./ChatKit/types";
+export type { KeyboardChatScrollViewProps } from "./KeyboardChatScrollView/types";

package/lib/typescript/index.d.ts

@@ -6,6 +6,6 @@ export * from "./constants";
 export * from "./module";
 export * from "./types";
 export * from "./compat";
-export { ChatKit, KeyboardAvoidingView, KeyboardStickyView, KeyboardAwareScrollView, KeyboardToolbar, DefaultKeyboardToolbarTheme, } from "./components";
-export type { ChatKitScrollViewProps, KeyboardAvoidingViewProps, KeyboardStickyViewProps, KeyboardAwareScrollViewProps, KeyboardAwareScrollViewRef, KeyboardToolbarProps, } from "./components";
+export { KeyboardChatScrollView, KeyboardAvoidingView, KeyboardStickyView, KeyboardAwareScrollView, KeyboardToolbar, DefaultKeyboardToolbarTheme, } from "./components";
+export type { KeyboardChatScrollViewProps, KeyboardAvoidingViewProps, KeyboardStickyViewProps, KeyboardAwareScrollViewProps, KeyboardAwareScrollViewRef, KeyboardToolbarProps, } from "./components";
 export { OverKeyboardView, KeyboardExtender } from "./views";

package/lib/typescript/specs/ClippingScrollViewDecoratorViewNativeComponent.d.ts

@@ -3,6 +3,8 @@ import type { ViewProps } from "react-native";
 import type { Double } from "react-native/Libraries/Types/CodegenTypes";
 export interface NativeProps extends ViewProps {
     contentInsetBottom: Double;
+    contentInsetTop: Double;
+    applyWorkaroundForContentInsetHitTestBug?: boolean;
 }
 declare const _default: HostComponent<NativeProps>;
 export default _default;

package/lib/typescript/specs/KeyboardToolbarGroupViewNativeComponent.d.ts

@@ -0,0 +1,6 @@
+import type { HostComponent } from "react-native";
+import type { ViewProps } from "react-native/Libraries/Components/View/ViewPropTypes";
+export interface NativeProps extends ViewProps {
+}
+declare const _default: HostComponent<NativeProps>;
+export default _default;

package/lib/typescript/specs/NativeKeyboardController.d.ts

@@ -6,6 +6,7 @@ export interface Spec extends TurboModule {
     preload(): void;
     dismiss(keepFocus: boolean, animated: boolean): void;
     setFocusTo(direction: string): void;
+    viewPositionInWindow(viewTag: number): Promise<object>;
     addListener: (eventName: string) => void;
     removeListeners: (count: number) => void;
 }

package/lib/typescript/types/module.d.ts

@@ -97,12 +97,19 @@ export type KeyboardControllerModule = {
      */
     state: () => KeyboardEventData;
 };
+export type ViewPositionInWindowResult = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
 export type KeyboardControllerNativeModule = {
     setDefaultMode: () => void;
     setInputMode: (mode: number) => void;
     preload: () => void;
     dismiss: (keepFocus: boolean, animated: boolean) => void;
     setFocusTo: (direction: Direction) => void;
+    viewPositionInWindow: (viewTag: number) => Promise<ViewPositionInWindowResult>;
     addListener: (eventName: string) => void;
     removeListeners: (count: number) => void;
 };

package/lib/typescript/types/views.d.ts

@@ -48,7 +48,11 @@ export type KeyboardExtenderProps = PropsWithChildren<{
     /** Controls whether this `KeyboardExtender` instance should take an effect. Default is `true`. */
     enabled?: boolean;
 }>;
+export type KeyboardToolbarGroupViewProps = PropsWithChildren<ViewProps>;
 export type ClippingScrollViewProps = PropsWithChildren<ViewProps & {
     /** An additional space that gets applied to the bottom of the `ScrollView` (inside a scrollable content). Default is `0`. */
     contentInsetBottom?: number;
+    /** An additional space that gets applied to the top of the `ScrollView` (inside a scrollable content). Default is `0`. */
+    contentInsetTop?: number;
+    applyWorkaroundForContentInsetHitTestBug?: boolean;
 }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-keyboard-controller",
-  "version": "1.21.0-beta.2",
+  "version": "1.21.0",
   "description": "Keyboard manager which works in identical way on both iOS and Android",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -67,6 +67,8 @@
     "keyboard next button",
     "keyboard previous button",
     "extend keyboard",
+    "chat",
+    "chat scroll view",
     "ios",
     "android"
   ],
@@ -191,7 +193,9 @@
         "KeyboardGestureArea": "KeyboardGestureArea",
         "OverKeyboardView": "OverKeyboardView",
         "KeyboardBackgroundView": "KeyboardBackgroundView",
-        "KeyboardExtender": "KeyboardExtender"
+        "KeyboardExtender": "KeyboardExtender",
+        "ClippingScrollViewDecoratorView": "ClippingScrollViewDecoratorView",
+        "KeyboardToolbarGroupView": "KeyboardToolbarGroupView"
       }
     }
   },

package/react-native.config.js

@@ -7,6 +7,8 @@ module.exports = {
           "KeyboardGestureAreaComponentDescriptor",
           "OverKeyboardViewComponentDescriptor",
           "KeyboardBackgroundViewComponentDescriptor",
+          "ClippingScrollViewDecoratorViewComponentDescriptor",
+          "KeyboardToolbarGroupViewComponentDescriptor",
         ],
         cmakeListsPath: "../android/src/main/jni/CMakeLists.txt",
       },

package/src/bindings.native.ts

@@ -1,7 +1,6 @@
 import { NativeEventEmitter, Platform } from "react-native";
 
 import type {
-  ClippingScrollViewProps,
   FocusedInputEventsModule,
   KeyboardBackgroundViewProps,
   KeyboardControllerNativeModule,
@@ -9,6 +8,7 @@ import type {
   KeyboardEventsModule,
   KeyboardExtenderProps,
   KeyboardGestureAreaProps,
+  KeyboardToolbarGroupViewProps,
   OverKeyboardViewProps,
   WindowDimensionsEventsModule,
 } from "./types";
@@ -73,6 +73,6 @@ export const RCTKeyboardExtender: React.FC<KeyboardExtenderProps> =
     ? require("./specs/KeyboardExtenderNativeComponent").default
     : ({ children }: KeyboardExtenderProps) => children;
 export const ClippingScrollView: React.FC<KeyboardBackgroundViewProps> =
-  Platform.OS === "android"
-    ? require("./specs/ClippingScrollViewDecoratorViewNativeComponent").default
-    : ({ children }: ClippingScrollViewProps) => children;
+  require("./specs/ClippingScrollViewDecoratorViewNativeComponent").default;
+export const RCTKeyboardToolbarGroupView: React.FC<KeyboardToolbarGroupViewProps> =
+  require("./specs/KeyboardToolbarGroupViewNativeComponent").default;

package/src/bindings.ts

@@ -9,6 +9,7 @@ import type {
   KeyboardEventsModule,
   KeyboardExtenderProps,
   KeyboardGestureAreaProps,
+  KeyboardToolbarGroupViewProps,
   OverKeyboardViewProps,
   WindowDimensionsEventsModule,
 } from "./types";
@@ -22,6 +23,8 @@ export const KeyboardControllerNative: KeyboardControllerNativeModule = {
   preload: NOOP,
   dismiss: NOOP,
   setFocusTo: NOOP,
+  viewPositionInWindow: () =>
+    Promise.resolve({ x: 0, y: 0, width: 0, height: 0 }),
   addListener: NOOP,
   removeListeners: NOOP,
 };
@@ -84,9 +87,20 @@ export const KeyboardBackgroundView =
 export const RCTKeyboardExtender =
   View as unknown as React.FC<KeyboardExtenderProps>;
 /**
- * A decorator that will clip the content of the `ScrollView`. It helps to simulate `contentInset` behavior on Android.
+ * A decorator that will clip the content of the `ScrollView`. It helps to simulate `contentInset` behavior on Android
  * Supports only `bottom` property (`paddingBottom` is not supported property of `ScrollView.style`).
  * Using this component we can modify bottom inset without having a fake view.
+ *
+ * On iOS we use swizzling to apply runtime patches to fix some broken internal methods.
+ * Ideally this component shouldn't exist and all its fixes/polyfills must be added directly to react-native and
+ * we will port features/fixes back to upstream, but at the moment we use this view to
+ * deliver desired functionality regardless of react-native version used.
  */
 export const ClippingScrollView =
   View as unknown as React.FC<ClippingScrollViewProps>;
+/**
+ * A View that defines a group of `TextInput`s.
+ * Used in toolbar navigation to assure that you can navigate only between inputs withing the same group.
+ */
+export const RCTKeyboardToolbarGroupView =
+  View as unknown as React.FC<KeyboardToolbarGroupViewProps>;

package/src/components/KeyboardAvoidingView/index.tsx

@@ -8,7 +8,10 @@ import Reanimated, {
   useSharedValue,
 } from "react-native-reanimated";
 
+import { KeyboardControllerNative } from "../../bindings";
 import { useWindowDimensions } from "../../hooks";
+import { findNodeHandle } from "../../utils/findNodeHandle";
+import useCombinedRef from "../hooks/useCombinedRef";
 
 import { useKeyboardAnimation, useTranslateAnimation } from "./hooks";
 
@@ -26,33 +29,29 @@ export type KeyboardAvoidingViewBaseProps = {
    * may be non-zero in some cases. Defaults to 0.
    */
   keyboardVerticalOffset?: number;
+
+  /**
+   * When `true`, the view automatically detects its position on screen,
+   * accounting for navigation headers, modals, and other layout offsets.
+   * This means `keyboardVerticalOffset` becomes purely additive extra
+   * space rather than compensation for unknown positioning.
+   *
+   * Defaults to `false` for backward compatibility.
+   */
+  automaticOffset?: boolean;
 } & ViewProps;
 
-export type KeyboardAvoidingViewProps = KeyboardAvoidingViewBaseProps &
-  (
-    | {
-        /**
-         * Specify how to react to the presence of the keyboard.
-         */
-        behavior?: "position";
-
-        /**
-         * Style of the content container when `behavior` is 'position'.
-         */
-        contentContainerStyle?: ViewProps["style"];
-      }
-    | {
-        /**
-         * Specify how to react to the presence of the keyboard.
-         */
-        behavior?: "height" | "padding" | "translate-with-padding";
-
-        /**
-         * `contentContainerStyle` is not allowed for these behaviors.
-         */
-        contentContainerStyle?: never;
-      }
-  );
+export type KeyboardAvoidingViewProps = KeyboardAvoidingViewBaseProps & {
+  /**
+   * Specify how to react to the presence of the keyboard.
+   */
+  behavior?: "height" | "padding" | "position" | "translate-with-padding";
+
+  /**
+   * Style of the content container when `behavior` is 'position'.
+   */
+  contentContainerStyle?: ViewProps["style"];
+};
 
 const defaultLayout: LayoutRectangle = {
   x: 0,
@@ -85,6 +84,7 @@ const KeyboardAvoidingView = forwardRef<
       contentContainerStyle,
       enabled = true,
       keyboardVerticalOffset = 0,
+      automaticOffset = false,
       style,
       onLayout: onLayoutProps,
       ...props
@@ -92,6 +92,7 @@ const KeyboardAvoidingView = forwardRef<
     ref,
   ) => {
     const initialFrame = useSharedValue<LayoutRectangle | null>(null);
+    const internalRef = React.useRef<View | null>(null);
     const frame = useDerivedValue(() => initialFrame.value || defaultLayout);
 
     const { translate, padding } = useTranslateAnimation();
@@ -132,10 +133,35 @@ const KeyboardAvoidingView = forwardRef<
     );
     const onLayout = useCallback<NonNullable<ViewProps["onLayout"]>>(
       (e) => {
-        runOnUI(onLayoutWorklet)(e.nativeEvent.layout);
         onLayoutProps?.(e);
+
+        const layout = e.nativeEvent.layout;
+
+        if (automaticOffset) {
+          const tag = findNodeHandle(internalRef.current);
+
+          if (tag !== null) {
+            // Use native `viewPositionInWindow` to get true screen-absolute coordinates.
+            // This fixes current RN bugs:
+            // - https://github.com/facebook/react-native/pull/56062
+            // - https://github.com/facebook/react-native/pull/56056
+            return KeyboardControllerNative.viewPositionInWindow(tag)
+              .then((position) => {
+                runOnUI(onLayoutWorklet)({
+                  ...layout,
+                  x: position.x,
+                  y: position.y,
+                });
+              })
+              .catch(() => {
+                runOnUI(onLayoutWorklet)(layout);
+              });
+          }
+        }
+
+        return runOnUI(onLayoutWorklet)(layout);
       },
-      [onLayoutProps],
+      [onLayoutProps, automaticOffset],
     );
 
     const animatedStyle = useAnimatedStyle(() => {
@@ -177,6 +203,7 @@ const KeyboardAvoidingView = forwardRef<
           return {};
       }
     }, [behavior, enabled, interpolateToRelativeKeyboardHeight]);
+    const combinedRef = useCombinedRef(internalRef, ref);
     const isPositionBehavior = behavior === "position";
     const containerStyle = isPositionBehavior ? contentContainerStyle : style;
     const combinedStyles = useMemo(
@@ -186,7 +213,7 @@ const KeyboardAvoidingView = forwardRef<
 
     if (isPositionBehavior) {
       return (
-        <View ref={ref} style={style} onLayout={onLayout} {...props}>
+        <View ref={combinedRef} style={style} onLayout={onLayout} {...props}>
           <Reanimated.View style={combinedStyles}>{children}</Reanimated.View>
         </View>
       );
@@ -194,7 +221,7 @@ const KeyboardAvoidingView = forwardRef<
 
     return (
       <Reanimated.View
-        ref={ref}
+        ref={combinedRef}
         style={combinedStyles}
         onLayout={onLayout}
         {...props}