@react-native-ohos/react-native-keyboard-controller 1.17.0-beta.2 → 1.17.1-rc.1

package/src/components/KeyboardAwareScrollView/useSmoothKeyboardHandler.ts

@@ -1,133 +1,133 @@
-import { Platform } from "react-native";
-import {
-  Easing,
-  useAnimatedReaction,
-  useSharedValue,
-  withTiming,
-} from "react-native-reanimated";
-
-import { useKeyboardHandler } from "../../hooks";
-
-const IS_ANDROID_ELEVEN_OR_HIGHER =
-  Platform.OS === "android" && Platform.Version >= 30;
-// on these platforms keyboard transitions will be smooth
-const IS_ANDROID_ELEVEN_OR_HIGHER_OR_IOS =
-  IS_ANDROID_ELEVEN_OR_HIGHER || Platform.OS === "ios" || Platform.OS as string === 'harmony';
-// on Android Telegram is not using androidx.core values and uses custom interpolation
-// duration is taken from here: https://github.com/DrKLO/Telegram/blob/e9a35cea54c06277c69d41b8e25d94b5d7ede065/TMessagesProj/src/main/java/org/telegram/ui/ActionBar/AdjustPanLayoutHelper.java#L39
-// and bezier is taken from: https://github.com/DrKLO/Telegram/blob/e9a35cea54c06277c69d41b8e25d94b5d7ede065/TMessagesProj/src/main/java/androidx/recyclerview/widget/ChatListItemAnimator.java#L40
-const TELEGRAM_ANDROID_TIMING_CONFIG = {
-  duration: 250,
-  easing: Easing.bezier(
-    0.19919472913616398,
-    0.010644531250000006,
-    0.27920937042459737,
-    0.91025390625,
-  ),
-};
-
-/**
- * Hook that uses default transitions for iOS and Android > 11, and uses
- * custom interpolation on Android < 11 to achieve more smooth animation
- */
-export const useSmoothKeyboardHandler: typeof useKeyboardHandler = (
-  handler,
-  deps,
-) => {
-  const target = useSharedValue(-1);
-  const height = useSharedValue(0);
-  const persistedHeight = useSharedValue(0);
-  const animatedKeyboardHeight = useSharedValue(0);
-
-  useAnimatedReaction(
-    () => {
-      if (IS_ANDROID_ELEVEN_OR_HIGHER_OR_IOS) {
-        return;
-      }
-      if (persistedHeight.value === 0) {
-        return;
-      }
-      const event = {
-        // it'll be always `TELEGRAM_ANDROID_TIMING_CONFIG.duration`, since we're running animation via `withTiming`
-        duration: TELEGRAM_ANDROID_TIMING_CONFIG.duration,
-        target: target.value,
-        height: animatedKeyboardHeight.value,
-        progress: animatedKeyboardHeight.value / persistedHeight.value,
-      };
-      return event;
-    },
-    (evt) => {
-      if (!evt) {
-        return;
-      }
-      handler.onMove?.(evt);
-
-      // dispatch `onEnd`
-      if (evt.height === height.value) {
-        handler.onEnd?.(evt);
-        // eslint-disable-next-line react-compiler/react-compiler
-        persistedHeight.value = height.value;
-      }
-    },
-    // REA uses own version of `DependencyList` and it's not compatible with the same type from React
-    deps as unknown[],
-  );
-
-  useKeyboardHandler(
-    {
-      onStart: (e) => {
-        "worklet";
-
-        // immediately dispatch onStart/onEnd events if onStart dispatched with the same height
-        // and don't wait for animation 250ms
-        if (
-          !IS_ANDROID_ELEVEN_OR_HIGHER_OR_IOS &&
-          e.height === persistedHeight.value
-        ) {
-          handler.onStart?.(e);
-          handler.onEnd?.(e);
-
-          return;
-        }
-
-        target.value = e.target;
-        height.value = e.height;
-
-        if (e.height > 0) {
-          persistedHeight.value = e.height;
-        }
-        // if we are running on Android < 9, then we are using custom interpolation
-        // to achieve smoother animation and use `animatedKeyboardHeight` as animation
-        // driver
-        if (!IS_ANDROID_ELEVEN_OR_HIGHER_OR_IOS) {
-          animatedKeyboardHeight.value = withTiming(
-            e.height,
-            TELEGRAM_ANDROID_TIMING_CONFIG,
-          );
-        }
-
-        handler.onStart?.({
-          ...e,
-          duration: IS_ANDROID_ELEVEN_OR_HIGHER_OR_IOS
-            ? e.duration
-            : TELEGRAM_ANDROID_TIMING_CONFIG.duration,
-        });
-      },
-      onMove: (e) => {
-        "worklet";
-
-        if (IS_ANDROID_ELEVEN_OR_HIGHER_OR_IOS) {
-          handler.onMove?.(e);
-        }
-      },
-      onEnd: (e) => {
-        "worklet";
-
-        if (IS_ANDROID_ELEVEN_OR_HIGHER_OR_IOS) {
-          handler.onEnd?.(e);
-        }
-      },
-    },
-    deps,
-  );
-};
+import { Platform } from "react-native";
+import {
+  Easing,
+  useAnimatedReaction,
+  useSharedValue,
+  withTiming,
+} from "react-native-reanimated";
+
+import { useKeyboardHandler } from "../../hooks";
+
+const IS_ANDROID_ELEVEN_OR_HIGHER =
+  Platform.OS === "android" && Platform.Version >= 30;
+// on these platforms keyboard transitions will be smooth
+const IS_ANDROID_ELEVEN_OR_HIGHER_OR_IOS =
+  IS_ANDROID_ELEVEN_OR_HIGHER || Platform.OS === "ios" || Platform.OS as string === 'harmony';
+// on Android Telegram is not using androidx.core values and uses custom interpolation
+// duration is taken from here: https://github.com/DrKLO/Telegram/blob/e9a35cea54c06277c69d41b8e25d94b5d7ede065/TMessagesProj/src/main/java/org/telegram/ui/ActionBar/AdjustPanLayoutHelper.java#L39
+// and bezier is taken from: https://github.com/DrKLO/Telegram/blob/e9a35cea54c06277c69d41b8e25d94b5d7ede065/TMessagesProj/src/main/java/androidx/recyclerview/widget/ChatListItemAnimator.java#L40
+const TELEGRAM_ANDROID_TIMING_CONFIG = {
+  duration: 250,
+  easing: Easing.bezier(
+    0.19919472913616398,
+    0.010644531250000006,
+    0.27920937042459737,
+    0.91025390625,
+  ),
+};
+
+/**
+ * Hook that uses default transitions for iOS and Android > 11, and uses
+ * custom interpolation on Android < 11 to achieve more smooth animation
+ */
+export const useSmoothKeyboardHandler: typeof useKeyboardHandler = (
+  handler,
+  deps,
+) => {
+  const target = useSharedValue(-1);
+  const height = useSharedValue(0);
+  const persistedHeight = useSharedValue(0);
+  const animatedKeyboardHeight = useSharedValue(0);
+
+  useAnimatedReaction(
+    () => {
+      if (IS_ANDROID_ELEVEN_OR_HIGHER_OR_IOS) {
+        return;
+      }
+      if (persistedHeight.value === 0) {
+        return;
+      }
+      const event = {
+        // it'll be always `TELEGRAM_ANDROID_TIMING_CONFIG.duration`, since we're running animation via `withTiming`
+        duration: TELEGRAM_ANDROID_TIMING_CONFIG.duration,
+        target: target.value,
+        height: animatedKeyboardHeight.value,
+        progress: animatedKeyboardHeight.value / persistedHeight.value,
+      };
+      return event;
+    },
+    (evt) => {
+      if (!evt) {
+        return;
+      }
+      handler.onMove?.(evt);
+
+      // dispatch `onEnd`
+      if (evt.height === height.value) {
+        handler.onEnd?.(evt);
+        // eslint-disable-next-line react-compiler/react-compiler
+        persistedHeight.value = height.value;
+      }
+    },
+    // create shallow copy (if deps specified) since `useAnimatedReaction` modifies them
+    deps ? [...deps] : deps,
+  );
+
+  useKeyboardHandler(
+    {
+      onStart: (e) => {
+        "worklet";
+
+        // immediately dispatch onStart/onEnd events if onStart dispatched with the same height
+        // and don't wait for animation 250ms
+        if (
+          !IS_ANDROID_ELEVEN_OR_HIGHER_OR_IOS &&
+          e.height === persistedHeight.value
+        ) {
+          handler.onStart?.(e);
+          handler.onEnd?.(e);
+
+          return;
+        }
+
+        target.value = e.target;
+        height.value = e.height;
+
+        if (e.height > 0) {
+          persistedHeight.value = e.height;
+        }
+        // if we are running on Android < 9, then we are using custom interpolation
+        // to achieve smoother animation and use `animatedKeyboardHeight` as animation
+        // driver
+        if (!IS_ANDROID_ELEVEN_OR_HIGHER_OR_IOS) {
+          animatedKeyboardHeight.value = withTiming(
+            e.height,
+            TELEGRAM_ANDROID_TIMING_CONFIG,
+          );
+        }
+
+        handler.onStart?.({
+          ...e,
+          duration: IS_ANDROID_ELEVEN_OR_HIGHER_OR_IOS
+            ? e.duration
+            : TELEGRAM_ANDROID_TIMING_CONFIG.duration,
+        });
+      },
+      onMove: (e) => {
+        "worklet";
+
+        if (IS_ANDROID_ELEVEN_OR_HIGHER_OR_IOS) {
+          handler.onMove?.(e);
+        }
+      },
+      onEnd: (e) => {
+        "worklet";
+
+        if (IS_ANDROID_ELEVEN_OR_HIGHER_OR_IOS) {
+          handler.onEnd?.(e);
+        }
+      },
+    },
+    deps,
+  );
+};

package/src/components/KeyboardAwareScrollView/utils.ts

@@ -1,41 +1,41 @@
-export const debounce = <F extends (...args: Parameters<F>) => ReturnType<F>>(
-  worklet: F,
-  wait = 0,
-) => {
-  "worklet";
-
-  const value = {
-    time: 0,
-  };
-
-  return (...args: Parameters<F>): ReturnType<F> | void => {
-    "worklet";
-
-    const t = Date.now();
-    const now = t - value.time;
-
-    if (now < wait) {
-      value.time = t;
-      return;
-    }
-
-    value.time = t;
-
-    return worklet(...args);
-  };
-};
-
-export const scrollDistanceWithRespectToSnapPoints = (
-  defaultScrollValue: number,
-  snapPoints?: number[],
-) => {
-  "worklet";
-
-  let snapPoint: number | undefined;
-
-  if (snapPoints) {
-    snapPoint = snapPoints.find((offset) => offset >= defaultScrollValue);
-  }
-
-  return snapPoint ?? defaultScrollValue;
-};
+export const debounce = <F extends (...args: Parameters<F>) => ReturnType<F>>(
+  worklet: F,
+  wait = 0,
+) => {
+  "worklet";
+
+  const value = {
+    time: 0,
+  };
+
+  return (...args: Parameters<F>): ReturnType<F> | void => {
+    "worklet";
+
+    const t = Date.now();
+    const now = t - value.time;
+
+    if (now < wait) {
+      value.time = t;
+      return;
+    }
+
+    value.time = t;
+
+    return worklet(...args);
+  };
+};
+
+export const scrollDistanceWithRespectToSnapPoints = (
+  defaultScrollValue: number,
+  snapPoints?: number[],
+) => {
+  "worklet";
+
+  let snapPoint: number | undefined;
+
+  if (snapPoints) {
+    snapPoint = snapPoints.find((offset) => offset >= defaultScrollValue);
+  }
+
+  return snapPoint ?? defaultScrollValue;
+};

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;