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

package/src/components/KeyboardChatScrollView/index.tsx

@@ -1,16 +1,25 @@
 import React, { forwardRef, useCallback, useMemo } from "react";
 import { StyleSheet } from "react-native";
-import { useAnimatedRef, useAnimatedStyle } from "react-native-reanimated";
+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>
@@ -23,6 +32,9 @@ const KeyboardChatScrollView = forwardRef<
       keyboardLiftBehavior = "always",
       freeze = false,
       offset = 0,
+      extraContentPadding = ZERO_CONTENT_PADDING,
+      blankSpace = ZERO_BLANK_SPACE,
+      applyWorkaroundForContentInsetHitTestBug = false,
       onLayout: onLayoutProp,
       onContentSizeChange: onContentSizeChangeProp,
       ...rest
@@ -31,11 +43,13 @@ const KeyboardChatScrollView = forwardRef<
   ) => {
     const scrollViewRef = useAnimatedRef<Reanimated.ScrollView>();
     const onRef = useCombinedRef(ref, scrollViewRef);
-
     const {
       padding,
       currentHeight,
       contentOffsetY,
+      scroll,
+      layout,
+      size,
       onLayout: onLayoutInternal,
       onContentSizeChange: onContentSizeChangeInternal,
     } = useChatKeyboard(scrollViewRef, {
@@ -43,8 +57,34 @@ const KeyboardChatScrollView = forwardRef<
       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);
@@ -81,9 +121,13 @@ const KeyboardChatScrollView = forwardRef<
         <ScrollViewWithBottomPadding
           ref={onRef}
           {...rest}
-          bottomPadding={padding}
+          applyWorkaroundForContentInsetHitTestBug={
+            applyWorkaroundForContentInsetHitTestBug
+          }
+          bottomPadding={totalPadding}
           contentOffsetY={contentOffsetY}
           inverted={inverted}
+          scrollIndicatorPadding={indicatorPadding}
           ScrollViewComponent={ScrollViewComponent}
           onContentSizeChange={onContentSizeChange}
           onLayout={onLayout}

package/src/components/KeyboardChatScrollView/types.ts

@@ -1,6 +1,7 @@
 import type { AnimatedScrollViewComponent } 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`. */
@@ -46,4 +47,44 @@ export type KeyboardChatScrollViewProps = {
    * 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

@@ -6,7 +6,7 @@ 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).
+ * 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).
@@ -18,11 +18,11 @@ const AT_END_THRESHOLD = 20;
  * getEffectiveHeight(150, 300, 50); // 125
  * ```
  */
-export function getEffectiveHeight(
+export const getEffectiveHeight = (
   height: number,
   targetKeyboardHeight: number,
   offset: number,
-): number {
+): number => {
   "worklet";
 
   if (offset === 0 || targetKeyboardHeight === 0) {
@@ -34,7 +34,7 @@ export function getEffectiveHeight(
     [0, targetKeyboardHeight],
     [0, Math.max(targetKeyboardHeight - offset, 0)],
   );
-}
+};
 
 /**
  * Check whether the scroll view is at the end of its content.
@@ -54,12 +54,12 @@ export function getEffectiveHeight(
  * const atEndInverted = isScrollAtEnd(5, 800, 2000, true); // true (5 <= 20)
  * ```
  */
-export function isScrollAtEnd(
+export const isScrollAtEnd = (
   scrollOffset: number,
   layoutHeight: number,
   contentHeight: number,
   inverted: boolean = false,
-): boolean {
+): boolean => {
   "worklet";
 
   if (inverted) {
@@ -67,7 +67,7 @@ export function isScrollAtEnd(
   }
 
   return scrollOffset + layoutHeight >= contentHeight - AT_END_THRESHOLD;
-}
+};
 
 /**
  * Decide whether content should be shifted based on the keyboard lift behavior.
@@ -81,10 +81,10 @@ export function isScrollAtEnd(
  * shouldShiftContent("whenAtEnd", false); // false
  * ```
  */
-export function shouldShiftContent(
+export const shouldShiftContent = (
   behavior: KeyboardLiftBehavior,
   isAtEnd: boolean,
-): boolean {
+): boolean => {
   "worklet";
 
   switch (behavior) {
@@ -97,67 +97,172 @@ export function shouldShiftContent(
     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.
+ * @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 function clampedScrollTarget(
+export const clampedScrollTarget = (
   offsetBeforeScroll: number,
   keyboardHeight: number,
   contentHeight: number,
   layoutHeight: number,
-): number {
+  totalPaddingForMaxScroll?: number,
+): number => {
   "worklet";
 
-  const maxScroll = Math.max(contentHeight - layoutHeight + keyboardHeight, 0);
+  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.
+ * @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 function computeIOSContentOffset(
+export const computeIOSContentOffset = (
   relativeScroll: number,
   keyboardHeight: number,
   contentHeight: number,
   layoutHeight: number,
   inverted: boolean,
-): number {
+  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),
-      -keyboardHeight,
+      -paddingForMax,
     );
   }
 
-  const maxScroll = Math.max(contentHeight - layoutHeight + keyboardHeight, 0);
+  const maxScroll = Math.max(contentHeight - layoutHeight + paddingForMax, 0);
 
   return Math.min(Math.max(keyboardHeight + relativeScroll, 0), maxScroll);
-}
+};

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

@@ -6,6 +6,8 @@ import useScrollState from "../../hooks/useScrollState";
 import {
   computeIOSContentOffset,
   getEffectiveHeight,
+  getScrollEffective,
+  getVisibleMinimumPaddingFraction,
   isScrollAtEnd,
   shouldShiftContent,
 } from "./helpers";
@@ -34,12 +36,20 @@ function useChatKeyboard(
   scrollViewRef: AnimatedRef<Reanimated.ScrollView>,
   options: UseChatKeyboardOptions,
 ): UseChatKeyboardReturn {
-  const { inverted, keyboardLiftBehavior, freeze, offset } = options;
+  const {
+    inverted,
+    keyboardLiftBehavior,
+    freeze,
+    offset,
+    blankSpace,
+    extraContentPadding,
+  } = options;
 
   const padding = useSharedValue(0);
   const currentHeight = useSharedValue(0);
   const contentOffsetY = useSharedValue(0);
   const targetKeyboardHeight = useSharedValue(0);
+  const prevAbsorption = useSharedValue(0);
 
   const {
     layout,
@@ -76,32 +86,63 @@ function useChatKeyboard(
           inverted,
         );
 
-        // persistent mode: when keyboard shrinks, snap to end or hold position
+        // Scale minimum padding absorption by how much of it is visible.
+        // Fully visible → full absorption; fully off-screen → no absorption.
+        const visibleFraction = getVisibleMinimumPaddingFraction(
+          scroll.value,
+          layout.value.height,
+          size.value.height,
+          blankSpace.value,
+          inverted,
+        );
+        const visiblePadding = visibleFraction * blankSpace.value;
+        const minimumPaddingAbsorbed = Math.max(
+          0,
+          visiblePadding - extraContentPadding.value,
+        );
+        const scrollEffective = getScrollEffective(
+          effective,
+          minimumPaddingAbsorbed,
+        );
+        const actualTotalPadding = Math.max(
+          blankSpace.value,
+          effective + extraContentPadding.value,
+        );
+
+        // persistent mode: when keyboard shrinks, clamp to valid range
         if (
           keyboardLiftBehavior === "persistent" &&
           effective < padding.value
         ) {
           padding.value = effective;
+          prevAbsorption.value = minimumPaddingAbsorbed;
 
-          if (atEnd) {
-            if (inverted) {
-              contentOffsetY.value = -effective;
-            } else {
-              contentOffsetY.value = Math.max(
-                size.value.height - layout.value.height + effective,
-                0,
-              );
-            }
+          if (inverted) {
+            const maxScroll = Math.max(
+              size.value.height - layout.value.height,
+              0,
+            );
+
+            contentOffsetY.value = Math.max(
+              -actualTotalPadding,
+              Math.min(scroll.value, maxScroll),
+            );
           } else {
-            // Preserve current scroll position so the animated props
-            // don't re-apply the stale contentOffset from keyboard open
-            contentOffsetY.value = scroll.value;
+            const maxScroll = Math.max(
+              size.value.height - layout.value.height + actualTotalPadding,
+              0,
+            );
+
+            contentOffsetY.value = Math.max(
+              0,
+              Math.min(scroll.value, maxScroll),
+            );
           }
 
           return;
         }
 
-        // never mode: when keyboard shrinks and at end, snap to end
+        // never mode: when keyboard shrinks, clamp to valid range
         // to avoid ghost padding
         if (
           keyboardLiftBehavior === "never" &&
@@ -109,24 +150,47 @@ function useChatKeyboard(
           atEnd
         ) {
           padding.value = effective;
+          prevAbsorption.value = minimumPaddingAbsorbed;
 
           if (inverted) {
-            contentOffsetY.value = -effective;
+            const maxScroll = Math.max(
+              size.value.height - layout.value.height,
+              0,
+            );
+
+            contentOffsetY.value = Math.max(
+              -actualTotalPadding,
+              Math.min(scroll.value, maxScroll),
+            );
           } else {
+            const maxScroll = Math.max(
+              size.value.height - layout.value.height + actualTotalPadding,
+              0,
+            );
+
             contentOffsetY.value = Math.max(
-              size.value.height - layout.value.height + effective,
               0,
+              Math.min(scroll.value, maxScroll),
             );
           }
 
           return;
         }
 
+        // Undo only the scroll displacement that was actually applied
+        // (not the full padding, which includes the absorbed portion).
+        // Use the stored absorption from the previous event so that
+        // the unwind matches the shift that was originally applied.
+        const prevScrollEffective = getScrollEffective(
+          padding.value,
+          prevAbsorption.value,
+        );
         const relativeScroll = inverted
-          ? scroll.value + padding.value
-          : scroll.value - padding.value;
+          ? scroll.value + prevScrollEffective
+          : scroll.value - prevScrollEffective;
 
         padding.value = effective;
+        prevAbsorption.value = minimumPaddingAbsorbed;
 
         if (!shouldShiftContent(keyboardLiftBehavior, atEnd)) {
           // Preserve current scroll position so animated props
@@ -136,12 +200,25 @@ function useChatKeyboard(
           return;
         }
 
+        // When blankSpace fully absorbs the keyboard opening, preserve current scroll position
+        // (only when keyboard is open — effective > 0 — not when closing)
+        if (
+          scrollEffective === 0 &&
+          minimumPaddingAbsorbed > 0 &&
+          effective > 0
+        ) {
+          contentOffsetY.value = scroll.value;
+
+          return;
+        }
+
         contentOffsetY.value = computeIOSContentOffset(
           relativeScroll,
-          effective,
+          scrollEffective,
           size.value.height,
           layout.value.height,
           inverted,
+          actualTotalPadding,
         );
       },
       onMove: () => {
@@ -165,13 +242,16 @@ function useChatKeyboard(
         padding.value = effective;
       },
     },
-    [inverted, keyboardLiftBehavior, freeze, offset],
+    [inverted, keyboardLiftBehavior, freeze, offset, extraContentPadding],
   );
 
   return {
     padding,
     currentHeight,
     contentOffsetY,
+    scroll,
+    layout,
+    size,
     onLayout,
     onContentSizeChange,
   };