react-native-keyboard-controller 1.21.0-beta.1 → 1.21.0-beta.3

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["KeyboardAvoidingView","KeyboardStickyView","KeyboardAwareScrollView","KeyboardToolbar","DefaultKeyboardToolbarTheme","OverKeyboardView","KeyboardExtender"],"sources":["index.ts"],"sourcesContent":["export * from \"./bindings\";\nexport * from \"./animated\";\nexport * from \"./context\";\nexport * from \"./hooks\";\nexport * from \"./constants\";\nexport * from \"./module\";\nexport * from \"./types\";\nexport * from \"./compat\";\n\nexport {\n  KeyboardAvoidingView,\n  KeyboardStickyView,\n  KeyboardAwareScrollView,\n  // keyboard toolbar\n  KeyboardToolbar,\n  DefaultKeyboardToolbarTheme,\n} from \"./components\";\nexport type {\n  KeyboardAvoidingViewProps,\n  KeyboardStickyViewProps,\n  KeyboardAwareScrollViewProps,\n  KeyboardAwareScrollViewRef,\n  KeyboardToolbarProps,\n} from \"./components\";\nexport { OverKeyboardView, KeyboardExtender } from \"./views\";\n"],"mappings":"AAAA,cAAc,YAAY;AAC1B,cAAc,YAAY;AAC1B,cAAc,WAAW;AACzB,cAAc,SAAS;AACvB,cAAc,aAAa;AAC3B,cAAc,UAAU;AACxB,cAAc,SAAS;AACvB,cAAc,UAAU;AAExB,SACEA,oBAAoB,EACpBC,kBAAkB,EAClBC,uBAAuB;AACvB;AACAC,eAAe,EACfC,2BAA2B,QACtB,cAAc;AAQrB,SAASC,gBAAgB,EAAEC,gBAAgB,QAAQ,SAAS","ignoreList":[]}
+{"version":3,"names":["KeyboardChatScrollView","KeyboardAvoidingView","KeyboardStickyView","KeyboardAwareScrollView","KeyboardToolbar","DefaultKeyboardToolbarTheme","OverKeyboardView","KeyboardExtender"],"sources":["index.ts"],"sourcesContent":["export * from \"./bindings\";\nexport * from \"./animated\";\nexport * from \"./context\";\nexport * from \"./hooks\";\nexport * from \"./constants\";\nexport * from \"./module\";\nexport * from \"./types\";\nexport * from \"./compat\";\n\nexport {\n  KeyboardChatScrollView,\n  KeyboardAvoidingView,\n  KeyboardStickyView,\n  KeyboardAwareScrollView,\n  // keyboard toolbar\n  KeyboardToolbar,\n  DefaultKeyboardToolbarTheme,\n} from \"./components\";\nexport type {\n  KeyboardChatScrollViewProps,\n  KeyboardAvoidingViewProps,\n  KeyboardStickyViewProps,\n  KeyboardAwareScrollViewProps,\n  KeyboardAwareScrollViewRef,\n  KeyboardToolbarProps,\n} from \"./components\";\nexport { OverKeyboardView, KeyboardExtender } from \"./views\";\n"],"mappings":"AAAA,cAAc,YAAY;AAC1B,cAAc,YAAY;AAC1B,cAAc,WAAW;AACzB,cAAc,SAAS;AACvB,cAAc,aAAa;AAC3B,cAAc,UAAU;AACxB,cAAc,SAAS;AACvB,cAAc,UAAU;AAExB,SACEA,sBAAsB,EACtBC,oBAAoB,EACpBC,kBAAkB,EAClBC,uBAAuB;AACvB;AACAC,eAAe,EACfC,2BAA2B,QACtB,cAAc;AASrB,SAASC,gBAAgB,EAAEC,gBAAgB,QAAQ,SAAS","ignoreList":[]}

package/lib/module/specs/ClippingScrollViewDecoratorViewNativeComponent.js.map

@@ -1 +1 @@
-{"version":3,"names":["codegenNativeComponent","interfaceOnly","excludedPlatforms"],"sources":["ClippingScrollViewDecoratorViewNativeComponent.ts"],"sourcesContent":["import { codegenNativeComponent } from \"react-native\";\n\nimport type { HostComponent } from \"react-native\";\nimport type { ViewProps } from \"react-native\";\nimport type { Double } from \"react-native/Libraries/Types/CodegenTypes\";\n\nexport interface NativeProps extends ViewProps {\n  contentInsetBottom: Double;\n}\n\nexport default codegenNativeComponent<NativeProps>(\n  \"ClippingScrollViewDecoratorView\",\n  {\n    interfaceOnly: true,\n    excludedPlatforms: [\"iOS\"],\n  },\n) as HostComponent<NativeProps>;\n"],"mappings":"AAAA,SAASA,sBAAsB,QAAQ,cAAc;AAUrD,eAAeA,sBAAsB,CACnC,iCAAiC,EACjC;EACEC,aAAa,EAAE,IAAI;EACnBC,iBAAiB,EAAE,CAAC,KAAK;AAC3B,CACF,CAAC","ignoreList":[]}
+{"version":3,"names":["codegenNativeComponent","interfaceOnly","excludedPlatforms"],"sources":["ClippingScrollViewDecoratorViewNativeComponent.ts"],"sourcesContent":["import { codegenNativeComponent } from \"react-native\";\n\nimport type { HostComponent } from \"react-native\";\nimport type { ViewProps } from \"react-native\";\nimport type { Double } from \"react-native/Libraries/Types/CodegenTypes\";\n\nexport interface NativeProps extends ViewProps {\n  contentInsetBottom: Double;\n  contentInsetTop: Double;\n}\n\nexport default codegenNativeComponent<NativeProps>(\n  \"ClippingScrollViewDecoratorView\",\n  {\n    interfaceOnly: true,\n    excludedPlatforms: [\"iOS\"],\n  },\n) as HostComponent<NativeProps>;\n"],"mappings":"AAAA,SAASA,sBAAsB,QAAQ,cAAc;AAWrD,eAAeA,sBAAsB,CACnC,iCAAiC,EACjC;EACEC,aAAa,EAAE,IAAI;EACnBC,iBAAiB,EAAE,CAAC,KAAK;AAC3B,CACF,CAAC","ignoreList":[]}

package/lib/module/types/views.js.map

@@ -1 +1 @@
-{"version":3,"names":[],"sources":["views.ts"],"sourcesContent":["import type { PropsWithChildren } from \"react\";\nimport type { ViewProps } from \"react-native\";\n\nexport type KeyboardGestureAreaProps = {\n  /**\n   * Determines how the keyboard position will be controlled:\n   * - `ios` - keyboard will be following finger only when finger touches keyboard\n   * - `linear` - keyboard will be following finger position linearly.\n   *\n   * @platform android\n   */\n  interpolator?: \"ios\" | \"linear\";\n  /**\n   * Whether to allow to show a keyboard from dismissed state by swipe up.\n   * Default to `false`.\n   *\n   * @platform android\n   */\n  showOnSwipeUp?: boolean;\n  /**\n   * Whether to allow to control a keyboard by gestures. The strategy how\n   * it should be controlled is determined by `interpolator` property.\n   * Defaults to `true`.\n   *\n   * @platform android\n   */\n  enableSwipeToDismiss?: boolean;\n  /**\n   * Extra distance to the keyboard.\n   */\n  offset?: number;\n  /**\n   * A corresponding `nativeID` value from the associated `TextInput` (a string that links the `KeyboardGestureArea` to one or more `TextInput` components).\n   * This is **required on iOS** in order to apply the `offset` when the keyboard is shown. Only the currently focused `TextInput` with a matching `nativeID`\n   * will receive offset behavior.\n   *\n   * @platform ios\n   */\n  textInputNativeID?: string;\n} & ViewProps;\nexport type OverKeyboardViewProps = PropsWithChildren<{\n  /**\n   * A boolean prop indicating whether the view is visible or not. If it's true then view is shown on the screen. If it's false then view is hidden.\n   */\n  visible: boolean;\n}>;\nexport type KeyboardBackgroundViewProps = PropsWithChildren<ViewProps>;\nexport type KeyboardExtenderProps = PropsWithChildren<{\n  /** Controls whether this `KeyboardExtender` instance should take an effect. Default is `true`. */\n  enabled?: boolean;\n}>;\nexport type ClippingScrollViewProps = PropsWithChildren<\n  ViewProps & {\n    /** An additional space that gets applied to the bottom of the `ScrollView` (inside a scrollable content). Default is `0`. */\n    contentInsetBottom?: number;\n  }\n>;\n"],"mappings":"","ignoreList":[]}
+{"version":3,"names":[],"sources":["views.ts"],"sourcesContent":["import type { PropsWithChildren } from \"react\";\nimport type { ViewProps } from \"react-native\";\n\nexport type KeyboardGestureAreaProps = {\n  /**\n   * Determines how the keyboard position will be controlled:\n   * - `ios` - keyboard will be following finger only when finger touches keyboard\n   * - `linear` - keyboard will be following finger position linearly.\n   *\n   * @platform android\n   */\n  interpolator?: \"ios\" | \"linear\";\n  /**\n   * Whether to allow to show a keyboard from dismissed state by swipe up.\n   * Default to `false`.\n   *\n   * @platform android\n   */\n  showOnSwipeUp?: boolean;\n  /**\n   * Whether to allow to control a keyboard by gestures. The strategy how\n   * it should be controlled is determined by `interpolator` property.\n   * Defaults to `true`.\n   *\n   * @platform android\n   */\n  enableSwipeToDismiss?: boolean;\n  /**\n   * Extra distance to the keyboard.\n   */\n  offset?: number;\n  /**\n   * A corresponding `nativeID` value from the associated `TextInput` (a string that links the `KeyboardGestureArea` to one or more `TextInput` components).\n   * This is **required on iOS** in order to apply the `offset` when the keyboard is shown. Only the currently focused `TextInput` with a matching `nativeID`\n   * will receive offset behavior.\n   *\n   * @platform ios\n   */\n  textInputNativeID?: string;\n} & ViewProps;\nexport type OverKeyboardViewProps = PropsWithChildren<{\n  /**\n   * A boolean prop indicating whether the view is visible or not. If it's true then view is shown on the screen. If it's false then view is hidden.\n   */\n  visible: boolean;\n}>;\nexport type KeyboardBackgroundViewProps = PropsWithChildren<ViewProps>;\nexport type KeyboardExtenderProps = PropsWithChildren<{\n  /** Controls whether this `KeyboardExtender` instance should take an effect. Default is `true`. */\n  enabled?: boolean;\n}>;\nexport type ClippingScrollViewProps = PropsWithChildren<\n  ViewProps & {\n    /** An additional space that gets applied to the bottom of the `ScrollView` (inside a scrollable content). Default is `0`. */\n    contentInsetBottom?: number;\n    /** An additional space that gets applied to the top of the `ScrollView` (inside a scrollable content). Default is `0`. */\n    contentInsetTop?: number;\n  }\n>;\n"],"mappings":"","ignoreList":[]}

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

@@ -0,0 +1,2 @@
+export { useChatKeyboard } from "./useChatKeyboard";
+export type { KeyboardLiftBehavior } from "./useChatKeyboard/types";

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

@@ -0,0 +1,12 @@
+import React from "react";
+import Reanimated from "react-native-reanimated";
+declare const KeyboardChatScrollView: React.ForwardRefExoticComponent<{
+    ScrollViewComponent?: import("../ScrollViewWithBottomPadding").AnimatedScrollViewComponent;
+    inverted?: boolean;
+    offset?: number;
+    keyboardLiftBehavior?: import("./hooks").KeyboardLiftBehavior;
+    freeze?: boolean;
+} & import("react-native").ScrollViewProps & {
+    children?: React.ReactNode | undefined;
+} & React.RefAttributes<Reanimated.ScrollView>>;
+export default KeyboardChatScrollView;

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

@@ -0,0 +1,48 @@
+import type { AnimatedScrollViewComponent } from "../ScrollViewWithBottomPadding";
+import type { KeyboardLiftBehavior } from "./useChatKeyboard/types";
+import type { ScrollViewProps } from "react-native";
+export type KeyboardChatScrollViewProps = {
+    /** Custom component for `ScrollView`. Default is `ScrollView`. */
+    ScrollViewComponent?: AnimatedScrollViewComponent;
+    /** Whether list are using `inverted` prop. Default is `false`. */
+    inverted?: boolean;
+    /**
+     * The distance between the bottom of the screen and the `ScrollView`.
+     * When the keyboard appears, the `ScrollView` will only push content by the effective
+     * distance (`keyboardHeight - offset`) instead of the full keyboard height.
+     *
+     * Useful when the input is not at the very bottom of the screen (e.g., above safe area, above
+     * bottom tabs, etc. - in this case offset should be equal to the height of the elements between
+     * `ScrollView` and bottom of the screen).
+     *
+     * Default is `0`.
+     */
+    offset?: number;
+    /**
+     * Determines how the chat content should behave when the keyboard appears, specifically whether
+     * the scroll view should automatically lift its content to keep it visible above the keyboard.
+     *
+     * Possible values:
+     * - `'always'`: The content always lifts along with the keyboard, ensuring the messages from the bottom part of screen
+     * remain visible regardless of the current scroll position. This is the default behavior for most chat applications (used in Telegram).
+     * - `'whenAtEnd'`: The content lifts only if the scroll view is at the end (i.e., the last message
+     * is visible or near the bottom). This prevents unnecessary adjustments when the user is scrolling
+     * through older messages (ChatGPT mobile app behavior).
+     * - `'persistent'`: The content always lifts when the keyboard appears (similar to `'always'`), but
+     * does not reset (lower) when the keyboard hides. This mimics behaviors where the view remains adjusted
+     * after keyboard dismissal to maintain focus on the latest content without shifting back (Claude mobile app behavior).
+     * - `'never'`: The content does not lift at all when the keyboard appears. Use this for scenarios
+     * when you don't want to disturb user attention with animations (Perplexity mobile app behavior).
+     *
+     * Default is `'always'`.
+     */
+    keyboardLiftBehavior?: KeyboardLiftBehavior;
+    /**
+     * When `true`, freezes all keyboard-driven layout changes (padding, content offset, scroll position).
+     * Useful when dismissing the keyboard to open a bottom sheet — prevents visual disruption
+     * while the sheet is visible.
+     *
+     * Default is `false`.
+     */
+    freeze?: boolean;
+} & ScrollViewProps;

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

@@ -0,0 +1,77 @@
+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 function 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 function 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 function shouldShiftContent(behavior: KeyboardLiftBehavior, isAtEnd: boolean): boolean;
+/**
+ * Compute the clamped scroll target for non-inverted lists.
+ *
+ * @param offsetBeforeScroll - Scroll position before keyboard appeared.
+ * @param keyboardHeight - Current keyboard height.
+ * @param contentHeight - Total height of the scrollable content.
+ * @param layoutHeight - Visible height of the scroll view.
+ * @returns Clamped scroll target between 0 and maxScroll.
+ * @example
+ * ```ts
+ * clampedScrollTarget(100, 300, 1000, 800); // 400
+ * ```
+ */
+export declare function clampedScrollTarget(offsetBeforeScroll: number, keyboardHeight: number, contentHeight: number, layoutHeight: number): number;
+/**
+ * Compute contentOffset.y for iOS lists.
+ *
+ * @param relativeScroll - Scroll position relative to current inset.
+ * @param keyboardHeight - Target keyboard height.
+ * @param contentHeight - Total height of the scrollable content.
+ * @param layoutHeight - Visible height of the scroll view.
+ * @param inverted - Whether the list is inverted.
+ * @returns The absolute contentOffset.y to set.
+ * @example
+ * ```ts
+ * computeIOSContentOffset(100, 300, 1000, 800, false); // 400
+ * ```
+ */
+export declare function computeIOSContentOffset(relativeScroll: number, keyboardHeight: number, contentHeight: number, layoutHeight: number, inverted: boolean): number;

package/lib/typescript/components/KeyboardChatScrollView/useChatKeyboard/index.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 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, 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/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,22 @@
+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;
+};
+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;
+    /** 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/ScrollViewWithBottomPadding/index.d.ts

@@ -7,6 +7,9 @@ export type AnimatedScrollViewComponent = React.ForwardRefExoticComponent<Animat
 declare const ScrollViewWithBottomPadding: React.ForwardRefExoticComponent<{
     ScrollViewComponent: AnimatedScrollViewComponent;
     children?: React.ReactNode;
+    inverted?: boolean;
     bottomPadding: SharedValue<number>;
+    /** Absolute Y content offset (iOS only, for KeyboardChatScrollView). */
+    contentOffsetY?: SharedValue<number>;
 } & 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,7 +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 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 { 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 { KeyboardAvoidingView, KeyboardStickyView, KeyboardAwareScrollView, KeyboardToolbar, DefaultKeyboardToolbarTheme, } from "./components";
-export type { 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,7 @@ import type { ViewProps } from "react-native";
 import type { Double } from "react-native/Libraries/Types/CodegenTypes";
 export interface NativeProps extends ViewProps {
     contentInsetBottom: Double;
+    contentInsetTop: Double;
 }
 declare const _default: HostComponent<NativeProps>;
 export default _default;

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

@@ -51,4 +51,6 @@ export type KeyboardExtenderProps = PropsWithChildren<{
 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;
 }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-keyboard-controller",
-  "version": "1.21.0-beta.1",
+  "version": "1.21.0-beta.3",
   "description": "Keyboard manager which works in identical way on both iOS and Android",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -41,7 +41,7 @@
     "typescript": "tsc --noEmit --project tsconfig.build.json",
     "lint": "eslint --quiet \"**/*.{js,ts,tsx}\"",
     "lint-clang": "find ios/ -iname *.h -o -iname *.m -o -iname *.mm | grep -v -e Pods -e build | xargs clang-format -i -n --Werror",
-    "prepare": "bob build",
+    "prepare": "bob build > /dev/null 2>&1",
     "release": "release-it",
     "example": "yarn --cwd example",
     "pods": "cd example && pod-install --quiet",
@@ -89,6 +89,7 @@
     "@react-native/eslint-config": "0.81.4",
     "@release-it/conventional-changelog": "^2.0.0",
     "@testing-library/react-hooks": "^8.0.1",
+    "@testing-library/react-native": "^13.3.3",
     "@types/jest": "^29.5.13",
     "@types/react": "^19.0.0",
     "@types/react-test-renderer": "^19.0.0",
@@ -115,7 +116,7 @@
     "react-native": "0.81.4",
     "react-native-builder-bob": "^0.18.0",
     "react-native-reanimated": "3.19.2",
-    "react-test-renderer": "19.0.0",
+    "react-test-renderer": "19.1.0",
     "release-it": "^14.2.2",
     "typescript": "5.8.3"
   },
@@ -129,6 +130,12 @@
     "modulePathIgnorePatterns": [
       "<rootDir>/example/node_modules",
       "<rootDir>/lib/"
+    ],
+    "transformIgnorePatterns": [
+      "node_modules/(?!((jest-)?react-native|@react-native(-community)?|react-native-reanimated)/)"
+    ],
+    "setupFiles": [
+      "./jestSetup.js"
     ]
   },
   "commitlint": {
@@ -187,5 +194,6 @@
         "KeyboardExtender": "KeyboardExtender"
       }
     }
-  }
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

package/src/components/KeyboardAwareScrollView/index.tsx

@@ -497,11 +497,18 @@ const KeyboardAwareScrollView = forwardRef<
       () => {
         const scrollView = scrollViewRef.current;
 
-        const existingMethods = scrollView ? { ...scrollView } : {};
+        if (scrollView) {
+          const scrollViewWithMethods =
+            scrollView as KeyboardAwareScrollViewRef;
 
-        return {
-          ...existingMethods,
+          scrollViewWithMethods.assureFocusedInputVisible = () => {
+            synchronize();
+          };
 
+          return scrollViewWithMethods;
+        }
+
+        return {
           assureFocusedInputVisible: () => {
             synchronize();
           },

package/src/components/KeyboardChatScrollView/hooks.ts

@@ -0,0 +1,2 @@
+export { useChatKeyboard } from "./useChatKeyboard";
+export type { KeyboardLiftBehavior } from "./useChatKeyboard/types";

package/src/components/KeyboardChatScrollView/index.tsx

@@ -0,0 +1,106 @@
+import React, { forwardRef, useCallback, useMemo } from "react";
+import { StyleSheet } from "react-native";
+import { useAnimatedRef, useAnimatedStyle } from "react-native-reanimated";
+import Reanimated from "react-native-reanimated";
+
+import useCombinedRef from "../hooks/useCombinedRef";
+import ScrollViewWithBottomPadding from "../ScrollViewWithBottomPadding";
+
+import { useChatKeyboard } from "./useChatKeyboard";
+
+import type { KeyboardChatScrollViewProps } from "./types";
+import type { LayoutChangeEvent } from "react-native";
+
+const KeyboardChatScrollView = forwardRef<
+  Reanimated.ScrollView,
+  React.PropsWithChildren<KeyboardChatScrollViewProps>
+>(
+  (
+    {
+      children,
+      ScrollViewComponent = Reanimated.ScrollView,
+      inverted = false,
+      keyboardLiftBehavior = "always",
+      freeze = false,
+      offset = 0,
+      onLayout: onLayoutProp,
+      onContentSizeChange: onContentSizeChangeProp,
+      ...rest
+    },
+    ref,
+  ) => {
+    const scrollViewRef = useAnimatedRef<Reanimated.ScrollView>();
+    const onRef = useCombinedRef(ref, scrollViewRef);
+
+    const {
+      padding,
+      currentHeight,
+      contentOffsetY,
+      onLayout: onLayoutInternal,
+      onContentSizeChange: onContentSizeChangeInternal,
+    } = useChatKeyboard(scrollViewRef, {
+      inverted,
+      keyboardLiftBehavior,
+      freeze,
+      offset,
+    });
+
+    const onLayout = useCallback(
+      (e: LayoutChangeEvent) => {
+        onLayoutInternal(e);
+        onLayoutProp?.(e);
+      },
+      [onLayoutInternal, onLayoutProp],
+    );
+
+    const onContentSizeChange = useCallback(
+      (w: number, h: number) => {
+        onContentSizeChangeInternal(w, h);
+        onContentSizeChangeProp?.(w, h);
+      },
+      [onContentSizeChangeInternal, onContentSizeChangeProp],
+    );
+
+    // Invisible view whose animated style changes every frame during keyboard
+    // animation. On Fabric, this forces Reanimated to schedule a commit,
+    // which flushes the scrollTo call in the same frame (fixing de-synchronization).
+    // see https://github.com/software-mansion/react-native-reanimated/issues/9000
+    const commitStyle = useAnimatedStyle(
+      () => ({
+        transform: [{ translateY: -currentHeight.value }],
+      }),
+      [],
+    );
+    const commit = useMemo(
+      () => [styles.commitView, commitStyle],
+      [commitStyle],
+    );
+
+    return (
+      <>
+        <ScrollViewWithBottomPadding
+          ref={onRef}
+          {...rest}
+          bottomPadding={padding}
+          contentOffsetY={contentOffsetY}
+          inverted={inverted}
+          ScrollViewComponent={ScrollViewComponent}
+          onContentSizeChange={onContentSizeChange}
+          onLayout={onLayout}
+        >
+          {children}
+        </ScrollViewWithBottomPadding>
+        <Reanimated.View style={commit} />
+      </>
+    );
+  },
+);
+
+const styles = StyleSheet.create({
+  commitView: {
+    display: "none",
+    position: "absolute",
+  },
+});
+
+export default KeyboardChatScrollView;

package/src/components/KeyboardChatScrollView/types.ts

@@ -0,0 +1,49 @@
+import type { AnimatedScrollViewComponent } from "../ScrollViewWithBottomPadding";
+import type { KeyboardLiftBehavior } from "./useChatKeyboard/types";
+import type { ScrollViewProps } from "react-native";
+
+export type KeyboardChatScrollViewProps = {
+  /** Custom component for `ScrollView`. Default is `ScrollView`. */
+  ScrollViewComponent?: AnimatedScrollViewComponent;
+  /** Whether list are using `inverted` prop. Default is `false`. */
+  inverted?: boolean;
+  /**
+   * The distance between the bottom of the screen and the `ScrollView`.
+   * When the keyboard appears, the `ScrollView` will only push content by the effective
+   * distance (`keyboardHeight - offset`) instead of the full keyboard height.
+   *
+   * Useful when the input is not at the very bottom of the screen (e.g., above safe area, above
+   * bottom tabs, etc. - in this case offset should be equal to the height of the elements between
+   * `ScrollView` and bottom of the screen).
+   *
+   * Default is `0`.
+   */
+  offset?: number;
+  /**
+   * Determines how the chat content should behave when the keyboard appears, specifically whether
+   * the scroll view should automatically lift its content to keep it visible above the keyboard.
+   *
+   * Possible values:
+   * - `'always'`: The content always lifts along with the keyboard, ensuring the messages from the bottom part of screen
+   * remain visible regardless of the current scroll position. This is the default behavior for most chat applications (used in Telegram).
+   * - `'whenAtEnd'`: The content lifts only if the scroll view is at the end (i.e., the last message
+   * is visible or near the bottom). This prevents unnecessary adjustments when the user is scrolling
+   * through older messages (ChatGPT mobile app behavior).
+   * - `'persistent'`: The content always lifts when the keyboard appears (similar to `'always'`), but
+   * does not reset (lower) when the keyboard hides. This mimics behaviors where the view remains adjusted
+   * after keyboard dismissal to maintain focus on the latest content without shifting back (Claude mobile app behavior).
+   * - `'never'`: The content does not lift at all when the keyboard appears. Use this for scenarios
+   * when you don't want to disturb user attention with animations (Perplexity mobile app behavior).
+   *
+   * Default is `'always'`.
+   */
+  keyboardLiftBehavior?: KeyboardLiftBehavior;
+  /**
+   * When `true`, freezes all keyboard-driven layout changes (padding, content offset, scroll position).
+   * Useful when dismissing the keyboard to open a bottom sheet — prevents visual disruption
+   * while the sheet is visible.
+   *
+   * Default is `false`.
+   */
+  freeze?: boolean;
+} & ScrollViewProps;