@react-native-ohos/react-native-keyboard-controller 1.16.8 → 1.17.0

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,6 +29,12 @@ export type KeyboardAvoidingViewBaseProps = {
    * may be non-zero in some cases. Defaults to 0.
    */
   keyboardVerticalOffset?: number;
+
+  /**
+   * When true, detect the view position in the window automatically.
+   * keyboardVerticalOffset remains an additive offset.
+   */
+  automaticOffset?: boolean;
 } & ViewProps;
 
 export type KeyboardAvoidingViewProps = KeyboardAvoidingViewBaseProps &
@@ -76,6 +85,7 @@ const KeyboardAvoidingView = forwardRef<
       contentContainerStyle,
       enabled = true,
       keyboardVerticalOffset = 0,
+      automaticOffset = false,
       style,
       onLayout: onLayoutProps,
       ...props
@@ -83,6 +93,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();
@@ -106,35 +117,67 @@ const KeyboardAvoidingView = forwardRef<
       [relativeKeyboardHeight],
     );
 
-    const onLayoutWorklet = useCallback((layout: LayoutRectangle) => {
-      "worklet";
+    const onLayoutWorklet = useCallback(
+      (layout: LayoutRectangle) => {
+        "worklet";
 
-      if (keyboard.isClosed.value || initialFrame.value === null) {
-        // eslint-disable-next-line react-compiler/react-compiler
-        initialFrame.value = layout;
-      }
-    }, []);
+        if (
+          keyboard.isClosed.value ||
+          initialFrame.value === null ||
+          behavior !== "height"
+        ) {
+          // eslint-disable-next-line react-compiler/react-compiler
+          initialFrame.value = layout;
+        }
+      },
+      [behavior],
+    );
     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) {
+            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(() => {
+      if (!enabled) {
+        return {};
+      }
+
       const bottom = interpolateToRelativeKeyboardHeight(
         keyboard.progress.value,
       );
       const translateY = interpolateToRelativeKeyboardHeight(translate.value);
       const paddingBottom = interpolateToRelativeKeyboardHeight(padding.value);
-      const bottomHeight = enabled ? bottom : 0;
+      const height = frame.value.height - bottom;
 
-      switch (behavior)  {
+      switch (behavior) {
         case "height":
-          if (!keyboard.isClosed.value) {
+          if (!keyboard.isClosed.value && height > 0) {
             return {
-              height: frame.value.height - bottomHeight,
+              height,
               flex: 0,
             };
           }
@@ -142,21 +185,22 @@ const KeyboardAvoidingView = forwardRef<
           return {};
 
         case "position":
-          return { bottom: bottomHeight };
+          return { bottom };
 
         case "padding":
-          return { paddingBottom: bottomHeight };
+          return { paddingBottom: bottom };
 
         case "translate-with-padding":
           return {
             paddingBottom: paddingBottom,
-            transform: [{ translateY: -translateY}],
+            transform: [{ translateY: -translateY }],
           };
 
         default:
           return {};
       }
     }, [behavior, enabled, interpolateToRelativeKeyboardHeight]);
+    const combinedRef = useCombinedRef(internalRef, ref);
     const isPositionBehavior = behavior === "position";
     const containerStyle = isPositionBehavior ? contentContainerStyle : style;
     const combinedStyles = useMemo(
@@ -166,7 +210,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>
       );
@@ -174,7 +218,7 @@ const KeyboardAvoidingView = forwardRef<
 
     return (
       <Reanimated.View
-        ref={ref}
+        ref={combinedRef}
         onLayout={onLayout}
         style={combinedStyles}
         {...props}

package/src/components/KeyboardAwareScrollView/index.tsx

@@ -1,7 +1,14 @@
-import React, { forwardRef, useCallback, useMemo } from "react";
-import { findNodeHandle, Platform } from "react-native";
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+} from "react";
+import { Platform } from "react-native";
 import Reanimated, {
   interpolate,
+  runOnUI,
   scrollTo,
   useAnimatedReaction,
   useAnimatedRef,
@@ -10,11 +17,13 @@ import Reanimated, {
   useSharedValue,
 } from "react-native-reanimated";
 
+import { KeyboardControllerNative } from "../../bindings";
 import {
   useFocusedInputHandler,
   useReanimatedFocusedInput,
   useWindowDimensions,
 } from "../../hooks";
+import { findNodeHandle } from "../../utils/findNodeHandle";
 
 import { useSmoothKeyboardHandler } from "./useSmoothKeyboardHandler";
 import { debounce, scrollDistanceWithRespectToSnapPoints } from "./utils";
@@ -45,6 +54,10 @@ export type KeyboardAwareScrollViewProps = {
   ScrollViewComponent?: React.ComponentType<ScrollViewProps>;
 } & ScrollViewProps;
 
+export type KeyboardAwareScrollViewRef = ScrollView & {
+  assureFocusedInputVisible: () => void;
+};
+
 /*
  * Everything begins from `onStart` handler. This handler is called every time,
  * when keyboard changes its size or when focused `TextInput` was changed. In
@@ -84,7 +97,7 @@ export type KeyboardAwareScrollViewProps = {
  *
  */
 const KeyboardAwareScrollView = forwardRef<
-  ScrollView,
+  KeyboardAwareScrollViewRef,
   React.PropsWithChildren<KeyboardAwareScrollViewProps>
 >(
   (
@@ -112,23 +125,31 @@ const KeyboardAwareScrollView = forwardRef<
     const scrollBeforeKeyboardMovement = useSharedValue(0);
     const { input } = useReanimatedFocusedInput();
     const layout = useSharedValue<FocusedInputLayoutChangedEvent | null>(null);
+    const scrollViewPageY = useSharedValue(0);
 
     const { height } = useWindowDimensions();
 
     const onRef = useCallback((assignedRef: Reanimated.ScrollView) => {
-      if (typeof ref === "function") {
-        ref(assignedRef);
-      } else if (ref) {
-        ref.current = assignedRef;
-      }
-
       scrollViewAnimatedRef(assignedRef);
     }, []);
     const onScrollViewLayout = useCallback(
-      (e: LayoutChangeEvent) => {
-        scrollViewTarget.value = findNodeHandle(scrollViewAnimatedRef.current);
+      async (e: LayoutChangeEvent) => {
+        const handle = findNodeHandle(scrollViewAnimatedRef.current);
+
+        scrollViewTarget.value = handle;
 
         onLayout?.(e);
+
+        if (handle !== null) {
+          try {
+            const { y } =
+              await KeyboardControllerNative.viewPositionInWindow(handle);
+
+            scrollViewPageY.value = y;
+          } catch {
+            // Keep the previous top boundary when the view is not mounted yet.
+          }
+        }
       },
       [onLayout],
     );
@@ -175,9 +196,9 @@ const KeyboardAwareScrollView = forwardRef<
           return interpolatedScrollTo;
         }
 
-        if (absoluteY < 0) {
-          const positionOnScreen = visibleRect - inputHeight - bottomOffset;
-          const topOfScreen = scrollPosition.value + absoluteY;
+        if (point < scrollViewPageY.value) {
+          const positionOnScreen = visibleRect - bottomOffset;
+          const topOfScreen = scrollPosition.value + point;
 
           scrollTo(
             scrollViewAnimatedRef,
@@ -191,6 +212,26 @@ const KeyboardAwareScrollView = forwardRef<
       },
       [bottomOffset, enabled, height, rest.snapToOffsets],
     );
+    const performScrollWithPositionRestoration = useCallback(
+      (newPosition: number) => {
+        "worklet";
+
+        const prevScrollPosition = scrollPosition.value;
+
+        // eslint-disable-next-line react-compiler/react-compiler
+        scrollPosition.value = newPosition;
+        maybeScroll(keyboardHeight.value, true);
+        scrollPosition.value = prevScrollPosition;
+      },
+      [maybeScroll],
+    );
+
+    useEffect(() => {
+      // Recalculate from the pre-keyboard position to avoid accumulating an already applied offset.
+      runOnUI(performScrollWithPositionRestoration)(
+        scrollBeforeKeyboardMovement.value,
+      );
+    }, [bottomOffset]);
 
     const syncKeyboardFrame = useCallback(
       (e: NativeEvent) => {
@@ -211,7 +252,6 @@ const KeyboardAwareScrollView = forwardRef<
       (customHeight?: number) => {
         "worklet";
 
-        const prevScrollPosition = scrollPosition.value;
         const prevLayout = layout.value;
 
         if (!input.value?.layout) {
@@ -226,12 +266,27 @@ const KeyboardAwareScrollView = forwardRef<
             height: customHeight ?? input.value.layout.height,
           },
         };
-        scrollPosition.value = position.value;
-        maybeScroll(keyboardHeight.value, true);
-        scrollPosition.value = prevScrollPosition;
+        performScrollWithPositionRestoration(position.value);
         layout.value = prevLayout;
       },
-      [maybeScroll],
+      [performScrollWithPositionRestoration],
+    );
+    const assureFocusedInputVisible = useCallback(() => {
+      runOnUI(scrollFromCurrentPosition)();
+    }, [scrollFromCurrentPosition]);
+
+    useImperativeHandle(
+      ref,
+      () => {
+        const current = scrollViewAnimatedRef.current;
+        if (current) {
+          Object.assign(current, { assureFocusedInputVisible });
+          return current as unknown as KeyboardAwareScrollViewRef;
+        }
+
+        return { assureFocusedInputVisible } as KeyboardAwareScrollViewRef;
+      },
+      [assureFocusedInputVisible],
     );
     const onChangeText = useCallback(() => {
       "worklet";
@@ -388,7 +443,7 @@ const KeyboardAwareScrollView = forwardRef<
         scrollEventThrottle={16}
       >
         {children}
-        <Reanimated.View style={view} />
+        {enabled && <Reanimated.View style={view} />}
       </ScrollViewComponent>
     );
   },

package/src/components/KeyboardAwareScrollView/useSmoothKeyboardHandler.ts

@@ -69,8 +69,8 @@ export const useSmoothKeyboardHandler: typeof useKeyboardHandler = (
         persistedHeight.value = height.value;
       }
     },
-    // REA uses own version of `DependencyList` and it's not compatible with the same type from React
-    deps as unknown[],
+    // create shallow copy (if deps specified) since `useAnimatedReaction` modifies them
+    deps ? [...deps] : deps,
   );
 
   useKeyboardHandler(

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,164 @@
+import React, { forwardRef, useCallback, useMemo } from "react";
+import { StyleSheet } from "react-native";
+import {
+  makeMutable,
+  useAnimatedRef,
+  useAnimatedStyle,
+  useDerivedValue,
+} from "react-native-reanimated";
+import Reanimated from "react-native-reanimated";
+
+import useCombinedRef from "../hooks/useCombinedRef";
+import ScrollViewWithBottomPadding from "../ScrollViewWithBottomPadding";
+
+import { useChatKeyboard } from "./useChatKeyboard";
+import { useEndVisible } from "./useEndVisible";
+import { useExtraContentPadding } from "./useExtraContentPadding";
+
+import type { KeyboardChatScrollViewProps } from "./types";
+import type { LayoutChangeEvent } from "react-native";
+
+const ZERO_CONTENT_PADDING = makeMutable(0);
+const ZERO_BLANK_SPACE = makeMutable(0);
+
+const KeyboardChatScrollView = forwardRef<
+  Reanimated.ScrollView,
+  React.PropsWithChildren<KeyboardChatScrollViewProps>
+>(
+  (
+    {
+      children,
+      ScrollViewComponent = Reanimated.ScrollView,
+      inverted = false,
+      keyboardLiftBehavior = "always",
+      freeze = false,
+      offset = 0,
+      extraContentPadding = ZERO_CONTENT_PADDING,
+      blankSpace = ZERO_BLANK_SPACE,
+      applyWorkaroundForContentInsetHitTestBug = false,
+      onLayout: onLayoutProp,
+      onContentSizeChange: onContentSizeChangeProp,
+      onEndVisible,
+      ...rest
+    },
+    ref,
+  ) => {
+    const scrollViewRef = useAnimatedRef<Reanimated.ScrollView>();
+    const onRef = useCombinedRef(ref, scrollViewRef);
+    const freezeSV = useDerivedValue(() =>
+      typeof freeze === "boolean" ? freeze : freeze.value,
+    );
+    const {
+      padding,
+      currentHeight,
+      contentOffsetY,
+      scroll,
+      layout,
+      size,
+      onLayout: onLayoutInternal,
+      onContentSizeChange: onContentSizeChangeInternal,
+    } = useChatKeyboard(scrollViewRef, {
+      inverted,
+      keyboardLiftBehavior,
+      freeze: freezeSV,
+      offset,
+      blankSpace,
+      extraContentPadding,
+    });
+
+    useExtraContentPadding({
+      scrollViewRef,
+      extraContentPadding,
+      keyboardPadding: padding,
+      blankSpace,
+      scroll,
+      layout,
+      size,
+      contentOffsetY,
+      inverted,
+      keyboardLiftBehavior,
+      freeze: freezeSV,
+    });
+
+    useEndVisible({
+      scroll,
+      layout,
+      size,
+      inverted,
+      onEndVisible,
+    });
+
+    const totalPadding = useDerivedValue(() =>
+      Math.max(blankSpace.value, padding.value + extraContentPadding.value),
+    );
+
+    // Scroll indicator inset = keyboard + extraContentPadding (excludes blankSpace).
+    // Apps that render into the unsafe area can supply a negative
+    // scrollIndicatorInsets adjustment at the application layer.
+    const indicatorPadding = useDerivedValue(
+      () => padding.value + extraContentPadding.value,
+    );
+
+    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}
+          applyWorkaroundForContentInsetHitTestBug={
+            applyWorkaroundForContentInsetHitTestBug
+          }
+          bottomPadding={totalPadding}
+          contentOffsetY={contentOffsetY}
+          inverted={inverted}
+          scrollIndicatorPadding={indicatorPadding}
+          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,117 @@
+import type {
+  AnimatedScrollViewComponent,
+  ScrollViewContentInsets,
+} from "../ScrollViewWithBottomPadding";
+import type { KeyboardLiftBehavior } from "./useChatKeyboard/types";
+import type { ScrollViewProps } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
+
+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 | SharedValue<boolean>;
+  /**
+   * A shared value representing additional padding from external elements
+   * (e.g., a growing multiline `TextInput` in a `KeyboardStickyView`).
+   *
+   * When this value changes:
+   * - The scrollable range is always extended/contracted (via `contentInset`).
+   * - The scroll position is conditionally adjusted based on `keyboardLiftBehavior`.
+   *
+   * Default is `undefined` (no extra padding).
+   */
+  extraContentPadding?: SharedValue<number>;
+  /**
+   * When `true`, applies a runtime workaround for a React Native 0.81+ bug
+   * where the ScrollView's `contentInset` area does not respond to touch/scroll
+   * gestures (facebook/react-native#54123).
+   *
+   * This uses Objective-C runtime method swizzling on the ScrollView's container
+   * view, which is inherently fragile. Only enable if you are affected by the
+   * upstream bug and understand the risks.
+   *
+   * iOS only. Default is `false`.
+   */
+  applyWorkaroundForContentInsetHitTestBug?: boolean;
+  /**
+   * A shared value representing a minimum inset floor (in pixels).
+   *
+   * When set, the total bottom padding is computed as:
+   * `max(blankSpace, keyboardPadding + extraContentPadding)`
+   *
+   * This means the keyboard "absorbs" into the minimum padding rather than adding to it:
+   * - When `blankSpace >= keyboard + extraContentPadding`: content does NOT move on keyboard open/close.
+   * - When `blankSpace < keyboard + extraContentPadding`: content moves, but only by the excess amount.
+   *
+   * Useful in AI chat apps where a sent message needs space below it (to push it to the top
+   * of the viewport) while the AI response streams in, without that space causing extra movement
+   * when the keyboard opens.
+   *
+   * Default is `undefined` (equivalent to `0` — no minimum floor).
+   */
+  blankSpace?: SharedValue<number>;
+  /**
+   * Fires whenever the effective content inset changes — the static `contentInset`
+   * prop combined with the dynamic keyboard-driven padding.
+   *
+   * Useful on Android, where the synthetic content inset is not reflected in the native
+   * `onScroll` event payload. Consumers such as virtualized lists computing their own
+   * `scrollToEnd` target can use this to track the current inset alongside scroll offsets.
+   */
+  onContentInsetChange?: (insets: ScrollViewContentInsets) => void;
+  /**
+   * Fires whenever the visibility of the content "end" changes — both when the user
+   * arrives at the end and when they leave it. The boolean parameter reflects the new state.
+   *
+   * For non-inverted lists, the "end" is the bottom of the content. For inverted lists
+   * (`inverted={true}`), the "end" is the top of the scroll view, where the latest messages
+   * are rendered. The same internal detection drives `keyboardLiftBehavior="whenAtEnd"`.
+   *
+   * The callback can be either a plain JS function or a Reanimated worklet — the type is
+   * detected automatically. Worklets run on the UI thread; plain functions are dispatched
+   * via `runOnJS`.
+   *
+   * Fires once on mount with the initial state (after the scroll view has been measured).
+   */
+  onEndVisible?: (visible: boolean) => void;
+} & ScrollViewProps;