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

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

@@ -0,0 +1,163 @@
+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 function 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 function 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 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/KeyboardChatScrollView/useChatKeyboard/index.ios.ts

@@ -0,0 +1,180 @@
+import { useSharedValue } from "react-native-reanimated";
+
+import { useKeyboardHandler } from "../../../hooks";
+import useScrollState from "../../hooks/useScrollState";
+
+import {
+  computeIOSContentOffset,
+  getEffectiveHeight,
+  isScrollAtEnd,
+  shouldShiftContent,
+} from "./helpers";
+
+import type { UseChatKeyboardOptions, UseChatKeyboardReturn } from "./types";
+import type { AnimatedRef } from "react-native-reanimated";
+import type Reanimated from "react-native-reanimated";
+
+/**
+ * Hook that manages keyboard-driven scrolling for chat-style scroll views.
+ * Calculates padding (extra scrollable space) and content shift values,
+ * using iOS-specific strategy (contentOffset set once in onStart).
+ *
+ * @param scrollViewRef - Animated ref to the scroll view.
+ * @param options - Configuration for inverted and keyboardLiftBehavior.
+ * @returns Shared values for padding and contentOffsetY.
+ * @example
+ * ```tsx
+ * const { padding, contentOffsetY } = 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 currentHeight = useSharedValue(0);
+  const contentOffsetY = useSharedValue(0);
+  const targetKeyboardHeight = useSharedValue(0);
+
+  const {
+    layout,
+    size,
+    offset: scroll,
+    onLayout,
+    onContentSizeChange,
+  } = useScrollState(scrollViewRef);
+
+  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,
+          targetKeyboardHeight.value,
+          offset,
+        );
+
+        const atEnd = isScrollAtEnd(
+          scroll.value,
+          layout.value.height,
+          size.value.height,
+          inverted,
+        );
+
+        // persistent mode: when keyboard shrinks, snap to end or hold position
+        if (
+          keyboardLiftBehavior === "persistent" &&
+          effective < padding.value
+        ) {
+          padding.value = effective;
+
+          if (atEnd) {
+            if (inverted) {
+              contentOffsetY.value = -effective;
+            } else {
+              contentOffsetY.value = Math.max(
+                size.value.height - layout.value.height + effective,
+                0,
+              );
+            }
+          } else {
+            // Preserve current scroll position so the animated props
+            // don't re-apply the stale contentOffset from keyboard open
+            contentOffsetY.value = scroll.value;
+          }
+
+          return;
+        }
+
+        // never mode: when keyboard shrinks and at end, snap to end
+        // to avoid ghost padding
+        if (
+          keyboardLiftBehavior === "never" &&
+          effective < padding.value &&
+          atEnd
+        ) {
+          padding.value = effective;
+
+          if (inverted) {
+            contentOffsetY.value = -effective;
+          } else {
+            contentOffsetY.value = Math.max(
+              size.value.height - layout.value.height + effective,
+              0,
+            );
+          }
+
+          return;
+        }
+
+        const relativeScroll = inverted
+          ? scroll.value + padding.value
+          : scroll.value - padding.value;
+
+        padding.value = effective;
+
+        if (!shouldShiftContent(keyboardLiftBehavior, atEnd)) {
+          // Preserve current scroll position so animated props
+          // don't re-apply a stale contentOffset when padding changes
+          contentOffsetY.value = scroll.value;
+
+          return;
+        }
+
+        contentOffsetY.value = computeIOSContentOffset(
+          relativeScroll,
+          effective,
+          size.value.height,
+          layout.value.height,
+          inverted,
+        );
+      },
+      onMove: () => {
+        "worklet";
+
+        // iOS doesn't need per-frame updates (contentOffset handles it)
+      },
+      onEnd: (e) => {
+        "worklet";
+
+        if (freeze) {
+          return;
+        }
+
+        const effective = getEffectiveHeight(
+          e.height,
+          targetKeyboardHeight.value,
+          offset,
+        );
+
+        padding.value = effective;
+      },
+    },
+    [inverted, keyboardLiftBehavior, freeze, offset],
+  );
+
+  return {
+    padding,
+    currentHeight,
+    contentOffsetY,
+    onLayout,
+    onContentSizeChange,
+  };
+}
+
+export { useChatKeyboard };

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

@@ -0,0 +1,300 @@
+import { scrollTo, useSharedValue } from "react-native-reanimated";
+
+import { useKeyboardHandler } from "../../../hooks";
+import useScrollState from "../../hooks/useScrollState";
+
+import {
+  clampedScrollTarget,
+  getEffectiveHeight,
+  isScrollAtEnd,
+  shouldShiftContent,
+} from "./helpers";
+
+import type { UseChatKeyboardOptions, UseChatKeyboardReturn } from "./types";
+import type { AnimatedRef } from "react-native-reanimated";
+import type Reanimated from "react-native-reanimated";
+
+/**
+ * Hook that manages keyboard-driven scrolling for chat-style scroll views.
+ * Calculates padding (extra scrollable space) and content shift values,
+ * using per-frame scrollTo updates (Android and other platforms).
+ *
+ * @param scrollViewRef - Animated ref to the scroll view.
+ * @param options - Configuration for inverted and keyboardLiftBehavior.
+ * @returns Shared values for padding and contentOffsetY (always `undefined`).
+ * @example
+ * ```tsx
+ * const { padding, contentOffsetY } = 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 currentHeight = useSharedValue(0);
+  const offsetBeforeScroll = useSharedValue(0);
+  const targetKeyboardHeight = useSharedValue(0);
+  const closing = useSharedValue(false);
+
+  const {
+    layout,
+    size,
+    offset: scroll,
+    onLayout,
+    onContentSizeChange,
+  } = useScrollState(scrollViewRef);
+
+  const clampScrollIfNeeded = (effective: number) => {
+    "worklet";
+
+    const maxScroll = Math.max(
+      size.value.height - layout.value.height + effective,
+      0,
+    );
+
+    if (scroll.value > maxScroll) {
+      scrollTo(scrollViewRef, 0, maxScroll, false);
+    }
+  };
+
+  useKeyboardHandler(
+    {
+      onStart: (e) => {
+        "worklet";
+
+        if (freeze) {
+          return;
+        }
+
+        if (e.height > 0) {
+          // eslint-disable-next-line react-compiler/react-compiler
+          targetKeyboardHeight.value = e.height;
+          closing.value = false;
+        } else {
+          closing.value = true;
+        }
+
+        const effective = getEffectiveHeight(
+          e.height,
+          targetKeyboardHeight.value,
+          offset,
+        );
+
+        const atEnd = isScrollAtEnd(
+          scroll.value,
+          layout.value.height,
+          size.value.height,
+          inverted,
+        );
+
+        if (inverted && e.duration === -1) {
+          // Android inverted: skip post-interactive snap-back events
+          // (duration === -1 means the keyboard is re-establishing its
+          // position after an interactive gesture, not a real animation)
+          return;
+        } else if (e.height > 0) {
+          // Android: keyboard opening — set padding + capture scroll position
+          padding.value = effective;
+          offsetBeforeScroll.value = scroll.value;
+
+          if (!inverted && keyboardLiftBehavior === "whenAtEnd" && !atEnd) {
+            // Sentinel: don't scroll in onMove (non-inverted only)
+            offsetBeforeScroll.value = -1;
+          }
+        } else {
+          // Android: keyboard closing — re-capture scroll position
+          if (inverted) {
+            offsetBeforeScroll.value = scroll.value;
+          } else {
+            // Preserve "whenAtEnd" sentinel: if open didn't shift, close shouldn't either
+            if (offsetBeforeScroll.value !== -1) {
+              // Non-inverted: subtract padding to get the "natural" position
+              // so onMove smoothly scrolls back from where the user is now
+              offsetBeforeScroll.value = scroll.value - padding.value;
+            }
+          }
+        }
+      },
+      onMove: (e) => {
+        "worklet";
+
+        if (freeze) {
+          return;
+        }
+
+        currentHeight.value = e.height;
+
+        if (inverted) {
+          // Skip post-interactive snap-back (duration === -1)
+          if (e.duration === -1) {
+            return;
+          }
+
+          const effective = getEffectiveHeight(
+            e.height,
+            targetKeyboardHeight.value,
+            offset,
+          );
+
+          // Check if we should shift content based on position when keyboard started
+          const wasAtEnd = isScrollAtEnd(
+            offsetBeforeScroll.value,
+            layout.value.height,
+            size.value.height,
+            inverted,
+          );
+
+          // "never" at end: scroll along when keyboard closes to avoid jump
+          if (
+            keyboardLiftBehavior === "never" &&
+            wasAtEnd &&
+            effective < padding.value
+          ) {
+            padding.value = effective;
+            scrollTo(scrollViewRef, 0, 0, false);
+
+            return;
+          }
+
+          if (!shouldShiftContent(keyboardLiftBehavior, wasAtEnd)) {
+            // Closing, not shifting: reduce padding to avoid gap
+            if (closing.value && effective < padding.value) {
+              padding.value = effective;
+              clampScrollIfNeeded(effective);
+            }
+
+            return;
+          }
+
+          // Persistent: don't let shift decrease
+          if (keyboardLiftBehavior === "persistent") {
+            const currentShift =
+              offsetBeforeScroll.value + padding.value - scroll.value;
+
+            if (effective < currentShift) {
+              // When at end, allow scrolling back (snap to end + reduce padding)
+              if (wasAtEnd) {
+                padding.value = effective;
+                scrollTo(scrollViewRef, 0, 0, false);
+              } else if (closing.value) {
+                // Not at end: reduce padding to avoid gap
+                padding.value = effective;
+                clampScrollIfNeeded(effective);
+              }
+
+              return;
+            }
+          }
+
+          const target = offsetBeforeScroll.value + padding.value - effective;
+
+          scrollTo(scrollViewRef, 0, target, false);
+        } else {
+          const effective = getEffectiveHeight(
+            e.height,
+            targetKeyboardHeight.value,
+            offset,
+          );
+
+          // "never" closing: scroll along when at end to avoid jump
+          if (
+            keyboardLiftBehavior === "never" &&
+            closing.value &&
+            effective < padding.value
+          ) {
+            const wasAtEnd = isScrollAtEnd(
+              offsetBeforeScroll.value + padding.value,
+              layout.value.height,
+              size.value.height,
+              false,
+            );
+
+            if (wasAtEnd) {
+              const target = clampedScrollTarget(
+                offsetBeforeScroll.value,
+                effective,
+                size.value.height,
+                layout.value.height,
+              );
+
+              scrollTo(scrollViewRef, 0, target, false);
+            } else {
+              // Clamp to valid range as padding shrinks
+              clampScrollIfNeeded(effective);
+            }
+
+            return;
+          }
+
+          if (!shouldShiftContent(keyboardLiftBehavior, true)) {
+            return;
+          }
+
+          // "whenAtEnd" sentinel check
+          if (offsetBeforeScroll.value === -1) {
+            if (closing.value) {
+              // Keyboard didn't shift on open; ensure valid position on close
+              clampScrollIfNeeded(effective);
+            }
+
+            return;
+          }
+
+          // "persistent" closing: maintain position, clamped to valid range
+          if (keyboardLiftBehavior === "persistent" && closing.value) {
+            const keepAt = offsetBeforeScroll.value + padding.value;
+            const maxScroll = Math.max(
+              size.value.height - layout.value.height + effective,
+              0,
+            );
+
+            scrollTo(scrollViewRef, 0, Math.min(keepAt, maxScroll), false);
+
+            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,
+          targetKeyboardHeight.value,
+          offset,
+        );
+
+        padding.value = effective;
+      },
+    },
+    [inverted, keyboardLiftBehavior, freeze, offset],
+  );
+
+  return {
+    padding,
+    currentHeight,
+    contentOffsetY: undefined,
+    onLayout,
+    onContentSizeChange,
+  };
+}
+
+export { useChatKeyboard };

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

@@ -0,0 +1,30 @@
+import type { LayoutChangeEvent } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
+
+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/contentInsetTop on Android. */
+  padding: SharedValue<number>;
+  /** Raw keyboard height updated every frame in onMove. Used to force Reanimated commits on Fabric. */
+  currentHeight: SharedValue<number>;
+  /** Absolute Y content offset for iOS (set once in onStart). `undefined` on Android. */
+  contentOffsetY: SharedValue<number> | undefined;
+  /** Callback to attach to ScrollView's onLayout prop to capture initial viewport dimensions. */
+  onLayout: (e: LayoutChangeEvent) => void;
+  /** Callback to attach to ScrollView's onContentSizeChange prop to capture initial content dimensions. */
+  onContentSizeChange: (w: number, h: number) => void;
+};
+
+export type {
+  KeyboardLiftBehavior,
+  UseChatKeyboardOptions,
+  UseChatKeyboardReturn,
+};

package/src/components/KeyboardStickyView/index.tsx

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