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

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

@@ -0,0 +1,118 @@
+type KeyboardLiftBehavior = "always" | "whenAtEnd" | "persistent" | "never";
+
+const AT_END_THRESHOLD = 20;
+
+/**
+ * Check whether the scroll view is at the end of its content.
+ *
+ * @param scrollOffset - Current vertical scroll offset.
+ * @param layoutHeight - Visible height of the scroll view.
+ * @param contentHeight - Total height of the scrollable content.
+ * @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)
+ * ```
+ */
+export function isScrollAtEnd(
+  scrollOffset: number,
+  layoutHeight: number,
+  contentHeight: number,
+): boolean {
+  "worklet";
+
+  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 function 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 clamped scroll target for non-inverted lists.
+ *
+ * @param offsetBeforeScroll - Scroll position before keyboard appeared.
+ * @param keyboardHeight - Current keyboard height.
+ * @param contentHeight - Total height of the scrollable content.
+ * @param layoutHeight - Visible height of the scroll view.
+ * @returns Clamped scroll target between 0 and maxScroll.
+ * @example
+ * ```ts
+ * clampedScrollTarget(100, 300, 1000, 800); // 400
+ * ```
+ */
+export function clampedScrollTarget(
+  offsetBeforeScroll: number,
+  keyboardHeight: number,
+  contentHeight: number,
+  layoutHeight: number,
+): number {
+  "worklet";
+
+  const maxScroll = Math.max(contentHeight - layoutHeight + keyboardHeight, 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 contentHeight - Total height of the scrollable content.
+ * @param layoutHeight - Visible height of the scroll view.
+ * @param inverted - Whether the list is inverted.
+ * @returns The absolute contentOffset.y to set.
+ * @example
+ * ```ts
+ * computeIOSContentOffset(100, 300, 1000, 800, false); // 400
+ * ```
+ */
+export function computeIOSContentOffset(
+  relativeScroll: number,
+  keyboardHeight: number,
+  contentHeight: number,
+  layoutHeight: number,
+  inverted: boolean,
+): number {
+  "worklet";
+
+  if (inverted) {
+    const maxScroll = Math.max(contentHeight - layoutHeight, 0);
+
+    return Math.max(
+      Math.min(relativeScroll - keyboardHeight, maxScroll),
+      -keyboardHeight,
+    );
+  }
+
+  const maxScroll = Math.max(contentHeight - layoutHeight + keyboardHeight, 0);
+
+  return Math.min(Math.max(keyboardHeight + relativeScroll, 0), maxScroll);
+}

package/src/components/ChatKit/useChatKeyboard/index.ts

@@ -0,0 +1,228 @@
+import { Platform } from "react-native";
+import { interpolate, scrollTo, useSharedValue } from "react-native-reanimated";
+
+import { useKeyboardHandler } from "../../../hooks";
+import useScrollState from "../../hooks/useScrollState";
+
+import {
+  clampedScrollTarget,
+  computeIOSContentOffset,
+  isScrollAtEnd,
+  shouldShiftContent,
+} from "./helpers";
+
+import type { AnimatedRef, SharedValue } from "react-native-reanimated";
+import type Reanimated from "react-native-reanimated";
+
+const OS = Platform.OS;
+
+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 on Android. */
+  padding: SharedValue<number>;
+  /** Absolute Y content offset for iOS (set once in onStart). `undefined` on Android. */
+  contentOffsetY: SharedValue<number> | undefined;
+  /** TranslateY for the container wrapper on Android inverted lists. 0 otherwise. */
+  containerTranslateY: SharedValue<number>;
+};
+
+/**
+ * Hook that manages keyboard-driven scrolling for chat-style scroll views.
+ * Calculates padding (extra scrollable space) and content shift values,
+ * using the optimal strategy per platform.
+ *
+ * @param scrollViewRef - Animated ref to the scroll view.
+ * @param options - Configuration for inverted and keyboardLiftBehavior.
+ * @returns Shared values for padding, contentOffsetY (iOS), and containerTranslateY (Android inverted).
+ * @example
+ * ```tsx
+ * const { padding, contentOffsetY, containerTranslateY } = 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 contentOffsetY = useSharedValue(0);
+  const containerTranslateY = useSharedValue(0);
+  const offsetBeforeScroll = useSharedValue(0);
+  const targetKeyboardHeight = useSharedValue(0);
+
+  const { layout, size, offset: scroll } = useScrollState(scrollViewRef);
+
+  const getEffectiveHeight = (height: number): number => {
+    "worklet";
+
+    if (offset === 0 || targetKeyboardHeight.value === 0) {
+      return height;
+    }
+
+    return interpolate(
+      height,
+      [0, targetKeyboardHeight.value],
+      [0, Math.max(targetKeyboardHeight.value - offset, 0)],
+    );
+  };
+
+  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);
+
+        const atEnd = isScrollAtEnd(
+          scroll.value,
+          layout.value.height,
+          size.value.height,
+        );
+
+        if (OS === "ios") {
+          // iOS: set padding + contentOffset once in onStart
+          const relativeScroll = inverted
+            ? scroll.value + padding.value
+            : scroll.value - padding.value;
+
+          padding.value = effective;
+
+          if (!shouldShiftContent(keyboardLiftBehavior, atEnd)) {
+            return;
+          }
+
+          if (
+            keyboardLiftBehavior === "persistent" &&
+            effective < padding.value
+          ) {
+            return;
+          }
+
+          contentOffsetY.value = computeIOSContentOffset(
+            relativeScroll,
+            effective,
+            size.value.height,
+            layout.value.height,
+            inverted,
+          );
+        } else if (e.height > 0) {
+          // Android: keyboard opening — set padding + capture scroll position
+          padding.value = effective;
+          offsetBeforeScroll.value = scroll.value;
+
+          if (keyboardLiftBehavior === "whenAtEnd" && !atEnd) {
+            // Sentinel: don't scroll in onMove
+            offsetBeforeScroll.value = -1;
+          }
+        } else {
+          // Android: keyboard closing — re-capture from current position
+          // so onMove smoothly scrolls back from where the user is now
+          offsetBeforeScroll.value = scroll.value - padding.value;
+        }
+      },
+      onMove: (e) => {
+        "worklet";
+
+        if (freeze) {
+          return;
+        }
+
+        // iOS doesn't need per-frame updates (contentOffset handles it)
+        if (OS === "ios") {
+          return;
+        }
+
+        if (!shouldShiftContent(keyboardLiftBehavior, true)) {
+          return;
+        }
+
+        // "whenAtEnd" sentinel check
+        if (offsetBeforeScroll.value === -1) {
+          return;
+        }
+
+        const effective = getEffectiveHeight(e.height);
+
+        if (inverted) {
+          // Android inverted: translateY on container
+          if (
+            keyboardLiftBehavior === "persistent" &&
+            effective < Math.abs(containerTranslateY.value)
+          ) {
+            return;
+          }
+
+          containerTranslateY.value = -effective;
+        } else {
+          // Android non-inverted: scrollTo per-frame
+          if (
+            keyboardLiftBehavior === "persistent" &&
+            effective < scroll.value - offsetBeforeScroll.value
+          ) {
+            return;
+          }
+
+          const target = clampedScrollTarget(
+            offsetBeforeScroll.value,
+            effective,
+            size.value.height,
+            layout.value.height,
+          );
+
+          scrollTo(scrollViewRef, 0, target, false);
+        }
+      },
+      onEnd: (e) => {
+        "worklet";
+
+        if (freeze) {
+          return;
+        }
+
+        const effective = getEffectiveHeight(e.height);
+
+        padding.value = effective;
+
+        if (
+          OS !== "ios" &&
+          inverted &&
+          e.height === 0 &&
+          keyboardLiftBehavior !== "persistent"
+        ) {
+          containerTranslateY.value = 0;
+        }
+      },
+    },
+    [inverted, keyboardLiftBehavior, freeze, offset],
+  );
+
+  return {
+    padding,
+    contentOffsetY: OS === "ios" ? contentOffsetY : undefined,
+    containerTranslateY,
+  };
+}
+
+export { useChatKeyboard };
+export type { KeyboardLiftBehavior };

package/src/components/KeyboardAwareScrollView/index.tsx

@@ -149,7 +149,6 @@ const KeyboardAwareScrollView = forwardRef<
     const lastSelection =
       useSharedValue<FocusedInputSelectionChangedEvent | null>(null);
     const ghostViewSpace = useSharedValue(-1);
-    const pendingSelectionForFocus = useSharedValue(false);
 
     const { height } = useWindowDimensions();
 
@@ -325,18 +324,7 @@ const KeyboardAwareScrollView = forwardRef<
         lastSelection.value = e;
 
         if (e.target !== lastTarget) {
-          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);
-            }
-          }
-
+          // ignore this event, because "focus changed" event handled in `useSmoothKeyboardHandler`
           return;
         }
         // caret in the end + end coordinates has been changed -> we moved to a new line
@@ -354,12 +342,7 @@ const KeyboardAwareScrollView = forwardRef<
 
         onChangeTextHandler();
       },
-      [
-        scrollFromCurrentPosition,
-        onChangeTextHandler,
-        updateLayoutFromSelection,
-        maybeScroll,
-      ],
+      [scrollFromCurrentPosition, onChangeTextHandler],
     );
 
     useFocusedInputHandler(
@@ -392,7 +375,6 @@ const KeyboardAwareScrollView = forwardRef<
             // on back transition need to interpolate as [0, keyboardHeight]
             initialKeyboardSize.value = 0;
             scrollPosition.value = scrollBeforeKeyboardMovement.value;
-            pendingSelectionForFocus.value = false;
           }
 
           if (
@@ -409,31 +391,17 @@ const KeyboardAwareScrollView = forwardRef<
           // focus was changed
           if (focusWasChanged) {
             tag.value = e.target;
-
-            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 position of focused text input when keyboard starts to move
+            updateLayoutFromSelection();
             // 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) {
-            if (!pendingSelectionForFocus.value) {
-              // update position on scroll value, so `onEnd` handler
-              // will pick up correct values
-              position.value += maybeScroll(e.height, true);
-            }
+            // update position on scroll value, so `onEnd` handler
+            // will pick up correct values
+            position.value += maybeScroll(e.height, true);
           }
 
           ghostViewSpace.value =
@@ -467,10 +435,6 @@ const KeyboardAwareScrollView = forwardRef<
           keyboardHeight.value = e.height;
           scrollPosition.value = position.value;
 
-          if (e.height === 0) {
-            lastSelection.value = null;
-          }
-
           syncKeyboardFrame(e);
         },
       },

package/src/components/KeyboardStickyView/index.tsx

@@ -58,17 +58,16 @@ const KeyboardStickyView = forwardRef<
       outputRange: [closed, opened],
     });
 
-    const styles = useMemo(
-      () => [
+    const styles = useMemo(() => {
+      return [
         {
           transform: [
             { translateY: enabled ? Animated.add(height, offset) : closed },
           ],
         },
         style,
-      ],
-      [closed, enabled, height, offset, style],
-    );
+      ];
+    }, [closed, enabled, height, offset, style]);
 
     return (
       <Animated.View ref={ref} style={styles} {...props}>

package/src/components/ScrollViewWithBottomPadding/index.tsx

@@ -6,11 +6,12 @@ import { ClippingScrollView } from "../../bindings";
 
 import styles from "./styles";
 
-import type { ScrollViewProps } from "react-native";
+import type { ScrollViewProps, StyleProp, ViewStyle } from "react-native";
 import type { SharedValue } from "react-native-reanimated";
 
+const OS = Platform.OS;
 const ReanimatedClippingScrollView =
-  Platform.OS === "android"
+  OS === "android"
     ? Reanimated.createAnimatedComponent(ClippingScrollView)
     : ClippingScrollView;
 
@@ -25,7 +26,12 @@ export type AnimatedScrollViewComponent = React.ForwardRefExoticComponent<
 type ScrollViewWithBottomPaddingProps = {
   ScrollViewComponent: AnimatedScrollViewComponent;
   children?: React.ReactNode;
+  inverted?: boolean;
   bottomPadding: SharedValue<number>;
+  /** Absolute Y content offset (iOS only, for ChatKit). */
+  contentOffsetY?: SharedValue<number>;
+  /** Style applied to the container wrapper (Android only, for ChatKit translateY). */
+  containerStyle?: StyleProp<ViewStyle>;
 } & ScrollViewProps;
 
 const ScrollViewWithBottomPadding = forwardRef<
@@ -33,35 +39,78 @@ const ScrollViewWithBottomPadding = forwardRef<
   ScrollViewWithBottomPaddingProps
 >(
   (
-    { ScrollViewComponent, bottomPadding, contentInset, children, ...rest },
+    {
+      ScrollViewComponent,
+      bottomPadding,
+      contentInset,
+      scrollIndicatorInsets,
+      inverted,
+      contentOffsetY,
+      containerStyle,
+      children,
+      style,
+      ...rest
+    },
     ref,
   ) => {
-    const animatedProps = useAnimatedProps(
-      () => ({
+    const animatedProps = useAnimatedProps(() => {
+      const bottom = inverted
+        ? 0
+        : bottomPadding.value + (contentInset?.bottom || 0);
+      const top = !inverted
+        ? 0
+        : bottomPadding.value + (contentInset?.top || 0);
+
+      const result: Record<string, unknown> = {
         // iOS prop
         contentInset: {
-          bottom: bottomPadding.value + (contentInset?.bottom || 0),
-          top: contentInset?.top,
+          bottom: bottom,
+          top: top,
           right: contentInset?.right,
           left: contentInset?.left,
         },
+        scrollIndicatorInsets: {
+          bottom: bottom,
+          top: top,
+          right: scrollIndicatorInsets?.right,
+          left: scrollIndicatorInsets?.left,
+        },
         // Android prop
         contentInsetBottom: bottomPadding.value,
-      }),
-      [
-        contentInset?.bottom,
-        contentInset?.top,
-        contentInset?.right,
-        contentInset?.left,
-      ],
-    );
+      };
+
+      if (contentOffsetY) {
+        result.contentOffset = { x: 0, y: contentOffsetY.value };
+      }
+
+      return result;
+    }, [
+      contentInset?.bottom,
+      contentInset?.top,
+      contentInset?.right,
+      contentInset?.left,
+      scrollIndicatorInsets?.bottom,
+      scrollIndicatorInsets?.top,
+      scrollIndicatorInsets?.right,
+      scrollIndicatorInsets?.left,
+      inverted,
+      contentOffsetY,
+    ]);
 
     return (
       <ReanimatedClippingScrollView
         animatedProps={animatedProps}
-        style={styles.container}
+        style={[
+          styles.container,
+          OS === "android" ? containerStyle : undefined,
+        ]}
       >
-        <ScrollViewComponent ref={ref} animatedProps={animatedProps} {...rest}>
+        <ScrollViewComponent
+          ref={ref}
+          animatedProps={animatedProps}
+          style={style}
+          {...rest}
+        >
           {children}
         </ScrollViewComponent>
       </ReanimatedClippingScrollView>

package/src/components/index.ts

@@ -5,6 +5,7 @@ export {
   default as KeyboardToolbar,
   DefaultKeyboardToolbarTheme,
 } from "./KeyboardToolbar";
+export { default as ChatKit } from "./ChatKit";
 export type { KeyboardAvoidingViewProps } from "./KeyboardAvoidingView";
 export type { KeyboardStickyViewProps } from "./KeyboardStickyView";
 export type {
@@ -12,3 +13,4 @@ export type {
   KeyboardAwareScrollViewRef,
 } from "./KeyboardAwareScrollView";
 export type { KeyboardToolbarProps } from "./KeyboardToolbar";
+export type { ChatKitScrollViewProps } from "./ChatKit/types";

package/src/index.ts

@@ -8,6 +8,7 @@ export * from "./types";
 export * from "./compat";
 
 export {
+  ChatKit,
   KeyboardAvoidingView,
   KeyboardStickyView,
   KeyboardAwareScrollView,
@@ -16,6 +17,7 @@ export {
   DefaultKeyboardToolbarTheme,
 } from "./components";
 export type {
+  ChatKitScrollViewProps,
   KeyboardAvoidingViewProps,
   KeyboardStickyViewProps,
   KeyboardAwareScrollViewProps,