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

package/src/components/KeyboardAwareScrollView/index.tsx

@@ -16,6 +16,7 @@ import Reanimated, {
   useSharedValue,
 } from "react-native-reanimated";
 
+import { KeyboardControllerNative } from "../../bindings";
 import {
   useFocusedInputHandler,
   useReanimatedFocusedInput,
@@ -149,14 +150,26 @@ const KeyboardAwareScrollView = forwardRef<
     const lastSelection =
       useSharedValue<FocusedInputSelectionChangedEvent | null>(null);
     const ghostViewSpace = useSharedValue(-1);
+    const pendingSelectionForFocus = useSharedValue(false);
+    const scrollViewPageY = useSharedValue(0);
 
     const { height } = useWindowDimensions();
 
     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) {
+          const { y } = await KeyboardControllerNative.viewPositionInWindow(
+            handle,
+          );
+
+          scrollViewPageY.value = y;
+        }
       },
       [onLayout],
     );
@@ -204,7 +217,7 @@ const KeyboardAwareScrollView = forwardRef<
           return interpolatedScrollTo;
         }
 
-        if (point < 0) {
+        if (point < scrollViewPageY.value) {
           const positionOnScreen = visibleRect - bottomOffset;
           const topOfScreen = scrollPosition.value + point;
 
@@ -324,7 +337,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 +366,12 @@ const KeyboardAwareScrollView = forwardRef<
 
         onChangeTextHandler();
       },
-      [scrollFromCurrentPosition, onChangeTextHandler],
+      [
+        scrollFromCurrentPosition,
+        onChangeTextHandler,
+        updateLayoutFromSelection,
+        maybeScroll,
+      ],
     );
 
     useFocusedInputHandler(
@@ -375,6 +404,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 +421,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 +479,10 @@ const KeyboardAwareScrollView = forwardRef<
           keyboardHeight.value = e.height;
           scrollPosition.value = position.value;
 
+          if (e.height === 0) {
+            lastSelection.value = null;
+          }
+
           syncKeyboardFrame(e);
         },
       },
@@ -461,11 +509,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,150 @@
+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 { 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,
+      ...rest
+    },
+    ref,
+  ) => {
+    const scrollViewRef = useAnimatedRef<Reanimated.ScrollView>();
+    const onRef = useCombinedRef(ref, scrollViewRef);
+    const {
+      padding,
+      currentHeight,
+      contentOffsetY,
+      scroll,
+      layout,
+      size,
+      onLayout: onLayoutInternal,
+      onContentSizeChange: onContentSizeChangeInternal,
+    } = useChatKeyboard(scrollViewRef, {
+      inverted,
+      keyboardLiftBehavior,
+      freeze,
+      offset,
+      blankSpace,
+      extraContentPadding,
+    });
+
+    useExtraContentPadding({
+      scrollViewRef,
+      extraContentPadding,
+      keyboardPadding: padding,
+      blankSpace,
+      scroll,
+      layout,
+      size,
+      inverted,
+      keyboardLiftBehavior,
+      freeze,
+    });
+
+    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/{ChatKit → KeyboardChatScrollView}/types.ts

@@ -1,16 +1,16 @@
 import type { AnimatedScrollViewComponent } from "../ScrollViewWithBottomPadding";
+import type { KeyboardLiftBehavior } from "./useChatKeyboard/types";
 import type { ScrollViewProps } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
 
-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
@@ -47,4 +47,44 @@ export type ChatKitScrollViewProps = {
    * Default is `false`.
    */
   freeze?: 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>;
 } & ScrollViewProps;

package/src/components/KeyboardChatScrollView/useChatKeyboard/helpers.ts

@@ -0,0 +1,268 @@
+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 const 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 const 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;
+};
+
+/**
+ * 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 const shouldShiftContent = (
+  behavior: KeyboardLiftBehavior,
+  isAtEnd: boolean,
+): boolean => {
+  "worklet";
+
+  switch (behavior) {
+    case "always":
+      return true;
+    case "never":
+      return false;
+    case "whenAtEnd":
+      return isAtEnd;
+    case "persistent":
+      return true;
+  }
+};
+
+/**
+ * Compute the fraction of minimum padding space currently visible in the viewport (0–1).
+ *
+ * The minimum padding space lives in the scroll view's contentInset, NOT in the
+ * content itself.  So `contentHeight` (from onContentSizeChange / scroll
+ * events) does **not** include it.  The visible portion is how far the
+ * viewport extends past the content boundary into the inset area.
+ *
+ * For non-inverted lists the padding is in contentInset.bottom.
+ * For inverted lists the padding is in contentInset.top (negative scroll).
+ *
+ * @param scrollOffset - Current vertical scroll offset.
+ * @param layoutHeight - Visible height of the scroll view.
+ * @param contentHeight - Height of the scroll content (excludes insets).
+ * @param blankSpace - Size of the minimum padding inset area.
+ * @param inverted - Whether the list is inverted.
+ * @returns A value between 0 (padding fully off-screen) and 1 (padding fully visible).
+ * @example
+ * ```ts
+ * // Non-inverted: contentHeight=1500, layout=800, blankSpace=300
+ * getVisibleMinimumPaddingFraction(1500, 800, 1500, 300, false); // 1   (at end, viewport past content)
+ * getVisibleMinimumPaddingFraction(850, 800, 1500, 300, false);  // 0.5 (half padding visible)
+ * getVisibleMinimumPaddingFraction(700, 800, 1500, 300, false);  // 0   (padding off-screen)
+ * ```
+ */
+export const getVisibleMinimumPaddingFraction = (
+  scrollOffset: number,
+  layoutHeight: number,
+  contentHeight: number,
+  blankSpace: number,
+  inverted: boolean,
+): number => {
+  "worklet";
+
+  if (blankSpace <= 0) {
+    return 0;
+  }
+
+  if (inverted) {
+    // Minimum padding is in contentInset.top; visible when scroll < 0
+    return Math.max(0, Math.min(1, -scrollOffset / blankSpace));
+  }
+
+  // Minimum padding is in contentInset.bottom; visible when viewport extends past content
+  const pastContentEnd = scrollOffset + layoutHeight - contentHeight;
+
+  return Math.max(0, Math.min(1, pastContentEnd / blankSpace));
+};
+
+/**
+ * Compute how much of the minimum content padding absorbs the keyboard + extraContentPadding.
+ *
+ * @param blankSpace - Minimum inset floor.
+ * @param extraContentPadding - Extra content padding from external elements.
+ * @returns The portion of blankSpace that absorbs keyboard displacement.
+ * @example
+ * ```ts
+ * getMinimumPaddingAbsorbed(500, 20); // 480
+ * getMinimumPaddingAbsorbed(0, 20);   // 0
+ * ```
+ */
+export const getMinimumPaddingAbsorbed = (
+  blankSpace: number,
+  extraContentPadding: number,
+): number => {
+  "worklet";
+
+  return Math.max(0, blankSpace - extraContentPadding);
+};
+
+/**
+ * Compute the effective scroll displacement after minimum padding absorption.
+ *
+ * @param rawEffective - Raw effective keyboard height.
+ * @param minimumPaddingAbsorbed - Amount absorbed by minimum content padding.
+ * @returns The scroll displacement after subtracting the absorbed portion.
+ * @example
+ * ```ts
+ * getScrollEffective(300, 200); // 100
+ * getScrollEffective(300, 400); // 0
+ * ```
+ */
+export const getScrollEffective = (
+  rawEffective: number,
+  minimumPaddingAbsorbed: number,
+): number => {
+  "worklet";
+
+  return Math.max(0, rawEffective - minimumPaddingAbsorbed);
+};
+
+/**
+ * Compute the clamped scroll target for non-inverted lists.
+ *
+ * @param offsetBeforeScroll - Scroll position before keyboard appeared.
+ * @param keyboardHeight - Current keyboard height (used for scroll displacement).
+ * @param contentHeight - Total height of the scrollable content.
+ * @param layoutHeight - Visible height of the scroll view.
+ * @param totalPaddingForMaxScroll - Total padding to use for maxScroll calculation. When provided, used instead of keyboardHeight for the scrollable range. Defaults to keyboardHeight.
+ * @returns Clamped scroll target between 0 and maxScroll.
+ * @example
+ * ```ts
+ * clampedScrollTarget(100, 300, 1000, 800); // 400
+ * clampedScrollTarget(100, 100, 1000, 800, 500); // 200, maxScroll uses 500
+ * ```
+ */
+export const clampedScrollTarget = (
+  offsetBeforeScroll: number,
+  keyboardHeight: number,
+  contentHeight: number,
+  layoutHeight: number,
+  totalPaddingForMaxScroll?: number,
+): number => {
+  "worklet";
+
+  const paddingForMax =
+    totalPaddingForMaxScroll !== undefined
+      ? totalPaddingForMaxScroll
+      : keyboardHeight;
+  const maxScroll = Math.max(contentHeight - layoutHeight + paddingForMax, 0);
+
+  return Math.min(Math.max(offsetBeforeScroll + keyboardHeight, 0), maxScroll);
+};
+
+/**
+ * Compute contentOffset.y for iOS lists.
+ *
+ * @param relativeScroll - Scroll position relative to current inset.
+ * @param keyboardHeight - Target keyboard height (used for scroll displacement).
+ * @param contentHeight - Total height of the scrollable content.
+ * @param layoutHeight - Visible height of the scroll view.
+ * @param inverted - Whether the list is inverted.
+ * @param totalPaddingForMaxScroll - Total padding to use for maxScroll calculation. When provided, used instead of keyboardHeight for the scrollable range. Defaults to keyboardHeight.
+ * @returns The absolute contentOffset.y to set.
+ * @example
+ * ```ts
+ * computeIOSContentOffset(100, 300, 1000, 800, false); // 400
+ * ```
+ */
+export const computeIOSContentOffset = (
+  relativeScroll: number,
+  keyboardHeight: number,
+  contentHeight: number,
+  layoutHeight: number,
+  inverted: boolean,
+  totalPaddingForMaxScroll?: number,
+): number => {
+  "worklet";
+
+  const paddingForMax =
+    totalPaddingForMaxScroll !== undefined
+      ? totalPaddingForMaxScroll
+      : keyboardHeight;
+
+  if (inverted) {
+    const maxScroll = Math.max(contentHeight - layoutHeight, 0);
+
+    return Math.max(
+      Math.min(relativeScroll - keyboardHeight, maxScroll),
+      -paddingForMax,
+    );
+  }
+
+  const maxScroll = Math.max(contentHeight - layoutHeight + paddingForMax, 0);
+
+  return Math.min(Math.max(keyboardHeight + relativeScroll, 0), maxScroll);
+};