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

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

@@ -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,7 @@ declare const ScrollViewWithBottomPadding: React.ForwardRefExoticComponent<{
     children?: React.ReactNode;
     inverted?: boolean;
     bottomPadding: SharedValue<number>;
-    /** Absolute Y content offset (iOS only, for ChatKit). */
+    /** 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>;
 } & 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,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.2",
+  "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",

package/src/components/KeyboardAwareScrollView/index.tsx

@@ -149,6 +149,7 @@ const KeyboardAwareScrollView = forwardRef<
     const lastSelection =
       useSharedValue<FocusedInputSelectionChangedEvent | null>(null);
     const ghostViewSpace = useSharedValue(-1);
+    const pendingSelectionForFocus = useSharedValue(false);
 
     const { height } = useWindowDimensions();
 
@@ -324,7 +325,18 @@ const KeyboardAwareScrollView = forwardRef<
         lastSelection.value = e;
 
         if (e.target !== lastTarget) {
-          // ignore this event, because "focus changed" event handled in `useSmoothKeyboardHandler`
+          if (pendingSelectionForFocus.value) {
+            // selection arrived after onStart - complete the deferred setup
+            pendingSelectionForFocus.value = false;
+            updateLayoutFromSelection();
+
+            // if keyboard was already visible (focus change, no onMove expected),
+            // perform the deferred scroll now
+            if (!keyboardWillAppear.value && keyboardHeight.value > 0) {
+              position.value += maybeScroll(keyboardHeight.value, true);
+            }
+          }
+
           return;
         }
         // caret in the end + end coordinates has been changed -> we moved to a new line
@@ -342,7 +354,12 @@ const KeyboardAwareScrollView = forwardRef<
 
         onChangeTextHandler();
       },
-      [scrollFromCurrentPosition, onChangeTextHandler],
+      [
+        scrollFromCurrentPosition,
+        onChangeTextHandler,
+        updateLayoutFromSelection,
+        maybeScroll,
+      ],
     );
 
     useFocusedInputHandler(
@@ -375,6 +392,7 @@ const KeyboardAwareScrollView = forwardRef<
             // on back transition need to interpolate as [0, keyboardHeight]
             initialKeyboardSize.value = 0;
             scrollPosition.value = scrollBeforeKeyboardMovement.value;
+            pendingSelectionForFocus.value = false;
           }
 
           if (
@@ -391,17 +409,31 @@ const KeyboardAwareScrollView = forwardRef<
           // focus was changed
           if (focusWasChanged) {
             tag.value = e.target;
-            // save position of focused text input when keyboard starts to move
-            updateLayoutFromSelection();
+
+            if (lastSelection.value?.target === e.target) {
+              // selection arrived before onStart - use it to update layout
+              updateLayoutFromSelection();
+              pendingSelectionForFocus.value = false;
+            } else {
+              // selection hasn't arrived yet for the new target.
+              // use input layout as-is; will be refined when selection arrives.
+              if (input.value) {
+                layout.value = input.value;
+              }
+              pendingSelectionForFocus.value = true;
+            }
+
             // save current scroll position - when keyboard will hide we'll reuse
             // this value to achieve smooth hide effect
             scrollBeforeKeyboardMovement.value = position.value;
           }
 
           if (focusWasChanged && !keyboardWillAppear.value) {
-            // update position on scroll value, so `onEnd` handler
-            // will pick up correct values
-            position.value += maybeScroll(e.height, true);
+            if (!pendingSelectionForFocus.value) {
+              // update position on scroll value, so `onEnd` handler
+              // will pick up correct values
+              position.value += maybeScroll(e.height, true);
+            }
           }
 
           ghostViewSpace.value =
@@ -435,6 +467,10 @@ const KeyboardAwareScrollView = forwardRef<
           keyboardHeight.value = e.height;
           scrollPosition.value = position.value;
 
+          if (e.height === 0) {
+            lastSelection.value = null;
+          }
+
           syncKeyboardFrame(e);
         },
       },
@@ -461,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/{ChatKit → KeyboardChatScrollView}/types.ts

@@ -1,16 +1,15 @@
 import type { AnimatedScrollViewComponent } from "../ScrollViewWithBottomPadding";
+import type { KeyboardLiftBehavior } from "./useChatKeyboard/types";
 import type { ScrollViewProps } from "react-native";
 
-type KeyboardLiftBehavior = "always" | "whenAtEnd" | "persistent" | "never";
-
-export type ChatKitScrollViewProps = {
+export type KeyboardChatScrollViewProps = {
   /** Custom component for `ScrollView`. Default is `ScrollView`. */
-  ScrollViewComponent: AnimatedScrollViewComponent;
+  ScrollViewComponent?: AnimatedScrollViewComponent;
   /** Whether list are using `inverted` prop. Default is `false`. */
   inverted?: boolean;
   /**
-   * The distance (in pixels) between the bottom of the screen and the `ScrollView`.
-   * When the keyboard appears, the scroll view will only push content by the effective
+   * 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

package/src/components/{ChatKit → KeyboardChatScrollView}/useChatKeyboard/helpers.ts

@@ -1,26 +1,71 @@
-type KeyboardLiftBehavior = "always" | "whenAtEnd" | "persistent" | "never";
+import { interpolate } from "react-native-reanimated";
+
+import type { KeyboardLiftBehavior } from "./types";
 
 const AT_END_THRESHOLD = 20;
 
+/**
+ * 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 function getEffectiveHeight(
+  height: number,
+  targetKeyboardHeight: number,
+  offset: number,
+): number {
+  "worklet";
+
+  if (offset === 0 || targetKeyboardHeight === 0) {
+    return height;
+  }
+
+  return interpolate(
+    height,
+    [0, targetKeyboardHeight],
+    [0, Math.max(targetKeyboardHeight - offset, 0)],
+  );
+}
+
 /**
  * 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 function isScrollAtEnd(
   scrollOffset: number,
   layoutHeight: number,
   contentHeight: number,
+  inverted: boolean = false,
 ): boolean {
   "worklet";
 
+  if (inverted) {
+    return scrollOffset <= AT_END_THRESHOLD;
+  }
+
   return scrollOffset + layoutHeight >= contentHeight - AT_END_THRESHOLD;
 }
 

package/src/components/KeyboardChatScrollView/useChatKeyboard/index.ios.ts

@@ -0,0 +1,180 @@
+import { useSharedValue } from "react-native-reanimated";
+
+import { useKeyboardHandler } from "../../../hooks";
+import useScrollState from "../../hooks/useScrollState";
+
+import {
+  computeIOSContentOffset,
+  getEffectiveHeight,
+  isScrollAtEnd,
+  shouldShiftContent,
+} from "./helpers";
+
+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",
+ * });
+ * ```
+ */
+function useChatKeyboard(
+  scrollViewRef: AnimatedRef<Reanimated.ScrollView>,
+  options: UseChatKeyboardOptions,
+): UseChatKeyboardReturn {
+  const { inverted, keyboardLiftBehavior, freeze, offset } = options;
+
+  const padding = useSharedValue(0);
+  const currentHeight = useSharedValue(0);
+  const contentOffsetY = useSharedValue(0);
+  const targetKeyboardHeight = useSharedValue(0);
+
+  const {
+    layout,
+    size,
+    offset: scroll,
+    onLayout,
+    onContentSizeChange,
+  } = useScrollState(scrollViewRef);
+
+  useKeyboardHandler(
+    {
+      onStart: (e) => {
+        "worklet";
+
+        if (freeze) {
+          return;
+        }
+
+        if (e.height > 0) {
+          // eslint-disable-next-line react-compiler/react-compiler
+          targetKeyboardHeight.value = e.height;
+        }
+
+        const effective = getEffectiveHeight(
+          e.height,
+          targetKeyboardHeight.value,
+          offset,
+        );
+
+        const atEnd = isScrollAtEnd(
+          scroll.value,
+          layout.value.height,
+          size.value.height,
+          inverted,
+        );
+
+        // persistent mode: when keyboard shrinks, snap to end or hold position
+        if (
+          keyboardLiftBehavior === "persistent" &&
+          effective < padding.value
+        ) {
+          padding.value = effective;
+
+          if (atEnd) {
+            if (inverted) {
+              contentOffsetY.value = -effective;
+            } else {
+              contentOffsetY.value = Math.max(
+                size.value.height - layout.value.height + effective,
+                0,
+              );
+            }
+          } else {
+            // Preserve current scroll position so the animated props
+            // don't re-apply the stale contentOffset from keyboard open
+            contentOffsetY.value = scroll.value;
+          }
+
+          return;
+        }
+
+        // never mode: when keyboard shrinks and at end, snap to end
+        // to avoid ghost padding
+        if (
+          keyboardLiftBehavior === "never" &&
+          effective < padding.value &&
+          atEnd
+        ) {
+          padding.value = effective;
+
+          if (inverted) {
+            contentOffsetY.value = -effective;
+          } else {
+            contentOffsetY.value = Math.max(
+              size.value.height - layout.value.height + effective,
+              0,
+            );
+          }
+
+          return;
+        }
+
+        const relativeScroll = inverted
+          ? scroll.value + padding.value
+          : scroll.value - padding.value;
+
+        padding.value = effective;
+
+        if (!shouldShiftContent(keyboardLiftBehavior, atEnd)) {
+          // Preserve current scroll position so animated props
+          // don't re-apply a stale contentOffset when padding changes
+          contentOffsetY.value = scroll.value;
+
+          return;
+        }
+
+        contentOffsetY.value = computeIOSContentOffset(
+          relativeScroll,
+          effective,
+          size.value.height,
+          layout.value.height,
+          inverted,
+        );
+      },
+      onMove: () => {
+        "worklet";
+
+        // iOS doesn't need per-frame updates (contentOffset handles it)
+      },
+      onEnd: (e) => {
+        "worklet";
+
+        if (freeze) {
+          return;
+        }
+
+        const effective = getEffectiveHeight(
+          e.height,
+          targetKeyboardHeight.value,
+          offset,
+        );
+
+        padding.value = effective;
+      },
+    },
+    [inverted, keyboardLiftBehavior, freeze, offset],
+  );
+
+  return {
+    padding,
+    currentHeight,
+    contentOffsetY,
+    onLayout,
+    onContentSizeChange,
+  };
+}
+
+export { useChatKeyboard };