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

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

@@ -0,0 +1,374 @@
+import { scrollTo, useSharedValue } from "react-native-reanimated";
+
+import { useKeyboardHandler } from "../../../hooks";
+import useScrollState from "../../hooks/useScrollState";
+
+import {
+  clampedScrollTarget,
+  getEffectiveHeight,
+  getMinimumPaddingAbsorbed,
+  getScrollEffective,
+  getVisibleMinimumPaddingFraction,
+  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 } = useChatKeyboard(ref, { inverted: false, keyboardLiftBehavior: "always" });
+ * ```
+ */
+function useChatKeyboard(
+  scrollViewRef: AnimatedRef<Reanimated.ScrollView>,
+  options: UseChatKeyboardOptions,
+): UseChatKeyboardReturn {
+  const {
+    inverted,
+    keyboardLiftBehavior,
+    freeze,
+    offset,
+    blankSpace,
+    extraContentPadding,
+  } = options;
+
+  const padding = useSharedValue(0);
+  const currentHeight = useSharedValue(0);
+  const offsetBeforeScroll = useSharedValue(0);
+  const targetKeyboardHeight = useSharedValue(0);
+  const closing = useSharedValue(false);
+  const minimumPaddingFractionOnOpen = useSharedValue(0);
+  const actualOpenShift = useSharedValue(0);
+  const {
+    layout,
+    size,
+    offset: scroll,
+    onLayout,
+    onContentSizeChange,
+  } = useScrollState(scrollViewRef);
+  const clampScrollIfNeeded = (
+    effective: number,
+    totalPaddingForMaxScroll?: number,
+  ) => {
+    "worklet";
+
+    const paddingForMax =
+      totalPaddingForMaxScroll !== undefined
+        ? totalPaddingForMaxScroll
+        : effective;
+    const maxScroll = Math.max(
+      size.value.height - layout.value.height + paddingForMax,
+      0,
+    );
+
+    if (scroll.value > maxScroll) {
+      scrollTo(scrollViewRef, 0, maxScroll, false);
+    }
+  };
+
+  useKeyboardHandler(
+    {
+      onStart: (e) => {
+        "worklet";
+
+        if (freeze.value) {
+          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,
+        );
+
+        // 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 minimumPaddingAbsorbed =
+          visibleFraction >= 1
+            ? getMinimumPaddingAbsorbed(
+                blankSpace.value,
+                extraContentPadding.value,
+              )
+            : 0;
+        const scrollEffective = getScrollEffective(
+          effective,
+          minimumPaddingAbsorbed,
+        );
+
+        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
+          minimumPaddingFractionOnOpen.value = visibleFraction >= 1 ? 1 : 0;
+          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 if (!inverted && scrollEffective === 0) {
+            // blankSpace fully absorbs the keyboard — prevent scroll
+            offsetBeforeScroll.value = -1;
+          } else if (inverted && scrollEffective === 0) {
+            // blankSpace fully absorbs the keyboard — guard for inverted
+            offsetBeforeScroll.value = scroll.value;
+          }
+        } 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) {
+              // Use the actual displacement recorded at end of open animation
+              // (not the theoretical value) so close is symmetric with open
+              offsetBeforeScroll.value = scroll.value - actualOpenShift.value;
+            }
+          }
+        }
+      },
+      onMove: (e) => {
+        "worklet";
+
+        if (freeze.value) {
+          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,
+          );
+
+          const minimumPaddingAbsorbed =
+            getMinimumPaddingAbsorbed(
+              blankSpace.value,
+              extraContentPadding.value,
+            ) * minimumPaddingFractionOnOpen.value;
+          const scrollEffective = getScrollEffective(
+            effective,
+            minimumPaddingAbsorbed,
+          );
+          const actualTotalPadding = Math.max(
+            blankSpace.value,
+            effective + extraContentPadding.value,
+          );
+
+          // 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;
+
+            if (scrollEffective === 0 && minimumPaddingAbsorbed > 0) {
+              return;
+            }
+
+            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, actualTotalPadding);
+            }
+
+            return;
+          }
+
+          // When blankSpace fully absorbs the keyboard, skip scroll
+          if (scrollEffective === 0 && minimumPaddingAbsorbed > 0) {
+            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, actualTotalPadding);
+              }
+
+              return;
+            }
+          }
+
+          const target =
+            offsetBeforeScroll.value + padding.value - scrollEffective;
+
+          scrollTo(scrollViewRef, 0, target, false);
+        } else {
+          const effective = getEffectiveHeight(
+            e.height,
+            targetKeyboardHeight.value,
+            offset,
+          );
+
+          const minimumPaddingAbsorbed =
+            getMinimumPaddingAbsorbed(
+              blankSpace.value,
+              extraContentPadding.value,
+            ) * minimumPaddingFractionOnOpen.value;
+          const scrollEffective = getScrollEffective(
+            effective,
+            minimumPaddingAbsorbed,
+          );
+          const actualTotalPadding = Math.max(
+            blankSpace.value,
+            effective + extraContentPadding.value,
+          );
+
+          // "never" closing: clamp scroll to valid range as inset shrinks
+          if (
+            keyboardLiftBehavior === "never" &&
+            closing.value &&
+            effective < padding.value
+          ) {
+            clampScrollIfNeeded(effective, actualTotalPadding);
+
+            return;
+          }
+
+          if (!shouldShiftContent(keyboardLiftBehavior, true)) {
+            return;
+          }
+
+          // "whenAtEnd" sentinel check (also used for blankSpace full absorption)
+          if (offsetBeforeScroll.value === -1) {
+            if (closing.value) {
+              // Keyboard didn't shift on open; ensure valid position on close
+              clampScrollIfNeeded(effective, actualTotalPadding);
+            }
+            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 + actualTotalPadding,
+              0,
+            );
+
+            scrollTo(scrollViewRef, 0, Math.min(keepAt, maxScroll), false);
+            return;
+          }
+
+          const target = clampedScrollTarget(
+            offsetBeforeScroll.value,
+            scrollEffective,
+            size.value.height,
+            layout.value.height,
+            actualTotalPadding,
+          );
+
+          scrollTo(scrollViewRef, 0, target, false);
+
+          // Track actual (clamped) displacement during open for symmetric close
+          if (!closing.value) {
+            actualOpenShift.value = target - offsetBeforeScroll.value;
+          }
+        }
+      },
+      onEnd: (e) => {
+        "worklet";
+
+        if (freeze.value) {
+          return;
+        }
+
+        const effective = getEffectiveHeight(
+          e.height,
+          targetKeyboardHeight.value,
+          offset,
+        );
+
+        padding.value = effective;
+
+        // Record actual scroll displacement so close can be symmetric
+        if (effective > 0 && offsetBeforeScroll.value !== -1) {
+          actualOpenShift.value = scroll.value - offsetBeforeScroll.value;
+        }
+      },
+    },
+    [inverted, keyboardLiftBehavior, offset],
+  );
+
+  return {
+    padding,
+    currentHeight,
+    contentOffsetY: undefined,
+    scroll,
+    layout,
+    size,
+    onLayout,
+    onContentSizeChange,
+  };
+}
+
+export { useChatKeyboard };

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

@@ -0,0 +1,39 @@
+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: SharedValue<boolean>;
+  offset: number;
+  blankSpace: SharedValue<number>;
+  /** Extra content padding shared value — needed on iOS to correctly clamp contentOffset. */
+  extraContentPadding: SharedValue<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;
+  /** Current vertical scroll offset. */
+  scroll: SharedValue<number>;
+  /** Visible viewport dimensions. */
+  layout: SharedValue<{ width: number; height: number }>;
+  /** Total content dimensions. */
+  size: SharedValue<{ width: number; height: number }>;
+  /** 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/KeyboardChatScrollView/useEndVisible.ts

@@ -0,0 +1,66 @@
+import { useMemo } from "react";
+import {
+  runOnJS,
+  useAnimatedReaction,
+  useDerivedValue,
+} from "react-native-reanimated";
+
+import { isScrollAtEnd } from "./useChatKeyboard/helpers";
+
+import type { SharedValue } from "react-native-reanimated";
+
+type EndVisibleCallback = (visible: boolean) => void;
+
+type Options = {
+  scroll: SharedValue<number>;
+  layout: SharedValue<{ width: number; height: number }>;
+  size: SharedValue<{ width: number; height: number }>;
+  inverted: boolean;
+  onEndVisible?: EndVisibleCallback;
+};
+
+const hasWorkletHash = (value: unknown): boolean =>
+  typeof value === "function" &&
+  !!(value as unknown as Record<string, unknown>).__workletHash;
+
+export const useEndVisible = ({
+  scroll,
+  layout,
+  size,
+  inverted,
+  onEndVisible,
+}: Options) => {
+  const isWorklet = useMemo(() => hasWorkletHash(onEndVisible), [onEndVisible]);
+
+  const isAtEnd = useDerivedValue(() => {
+    // Wait until the scroll view has been measured to avoid a spurious initial
+    // `true` on a (0,0,0) layout (the helper would otherwise treat unmeasured
+    // state as "at end" because 0 + 0 >= 0 - threshold).
+    if (layout.value.height === 0 || size.value.height === 0) {
+      return null;
+    }
+
+    return isScrollAtEnd(
+      scroll.value,
+      layout.value.height,
+      size.value.height,
+      inverted,
+    );
+  });
+
+  useAnimatedReaction(
+    () => isAtEnd.value,
+    (current, previous) => {
+      if (current === null || current === previous || !onEndVisible) {
+        return;
+      }
+
+      if (isWorklet) {
+        onEndVisible(current);
+      } else {
+        runOnJS(onEndVisible)(current);
+      }
+    },
+    [onEndVisible, isWorklet, inverted],
+  );
+};

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

@@ -0,0 +1,149 @@
+import { useCallback } from "react";
+import { Platform } from "react-native";
+import { scrollTo, useAnimatedReaction } from "react-native-reanimated";
+
+import { IS_FABRIC } from "../../../architecture";
+import { isScrollAtEnd, shouldShiftContent } from "../useChatKeyboard/helpers";
+
+import type { KeyboardLiftBehavior } from "../useChatKeyboard/types";
+import type { AnimatedRef, SharedValue } from "react-native-reanimated";
+import type Reanimated from "react-native-reanimated";
+
+type UseExtraContentPaddingOptions = {
+  scrollViewRef: AnimatedRef<Reanimated.ScrollView>;
+  extraContentPadding: SharedValue<number>;
+  /** Keyboard-only padding from useChatKeyboard — used to compute total padding for clamping. */
+  keyboardPadding: SharedValue<number>;
+  /** Minimum inset floor — used to absorb keyboard and extraContentPadding changes. */
+  blankSpace: SharedValue<number>;
+  /** Current vertical scroll offset. */
+  scroll: SharedValue<number>;
+  /** Visible viewport dimensions. */
+  layout: SharedValue<{ width: number; height: number }>;
+  /** Total content dimensions. */
+  size: SharedValue<{ width: number; height: number }>;
+  /** IOS only — when provided, sets contentOffset atomically with contentInset. */
+  contentOffsetY?: SharedValue<number>;
+  inverted: boolean;
+  keyboardLiftBehavior: KeyboardLiftBehavior;
+  freeze: SharedValue<boolean>;
+};
+
+/**
+ * Hook that reacts to `extraContentPadding` changes and conditionally
+ * adjusts the scroll position using `scrollTo` on both iOS and Android.
+ *
+ * Padding extension (scrollable range) is handled externally via a
+ * `useDerivedValue` that sums keyboard padding + extra content padding.
+ * This hook only handles the scroll correction.
+ *
+ * @param options - Configuration and shared values.
+ * @example
+ * ```tsx
+ * useExtraContentPadding({ scrollViewRef, extraContentPadding, ... });
+ * ```
+ */
+function useExtraContentPadding(options: UseExtraContentPaddingOptions): void {
+  const {
+    scrollViewRef,
+    extraContentPadding,
+    keyboardPadding,
+    blankSpace,
+    scroll,
+    layout,
+    size,
+    contentOffsetY,
+    inverted,
+    keyboardLiftBehavior,
+    freeze,
+  } = options;
+
+  const scrollToTarget = useCallback(
+    (target: number) => {
+      "worklet";
+
+      if (contentOffsetY && IS_FABRIC) {
+        // eslint-disable-next-line react-compiler/react-compiler
+        contentOffsetY.value = target;
+      } else if (Platform.OS === "android" || (Platform.OS as string) === "harmony") {
+        // Defer scrollTo so the animatedProps inset commit lands first;
+        // otherwise the native ScrollView clamps to the old range.
+        requestAnimationFrame(() => {
+          scrollTo(scrollViewRef, 0, target, false);
+        });
+      } else {
+        scrollTo(scrollViewRef, 0, target, false);
+      }
+    },
+    [scrollViewRef, contentOffsetY],
+  );
+
+  useAnimatedReaction(
+    () => extraContentPadding.value,
+    (current, previous) => {
+      if (freeze.value || previous === null) {
+        return;
+      }
+
+      const rawDelta = current - previous;
+
+      if (rawDelta === 0) {
+        return;
+      }
+
+      // Compute effective delta considering blankSpace floor
+      const previousTotal = Math.max(
+        blankSpace.value,
+        keyboardPadding.value + previous,
+      );
+      const currentTotal = Math.max(
+        blankSpace.value,
+        keyboardPadding.value + current,
+      );
+      const effectiveDelta = currentTotal - previousTotal;
+
+      if (effectiveDelta === 0) {
+        // blankSpace absorbed the change
+        return;
+      }
+
+      const atEnd = isScrollAtEnd(
+        scroll.value,
+        layout.value.height,
+        size.value.height,
+        inverted,
+      );
+
+      // "persistent": scroll on grow, hold position on shrink (unless at end)
+      if (
+        keyboardLiftBehavior === "persistent" &&
+        effectiveDelta < 0 &&
+        !atEnd
+      ) {
+        return;
+      }
+
+      if (!shouldShiftContent(keyboardLiftBehavior, atEnd)) {
+        return;
+      }
+
+      if (inverted) {
+        const target = Math.max(scroll.value - effectiveDelta, -currentTotal);
+
+        scrollToTarget(target);
+      } else {
+        const maxScroll = Math.max(
+          size.value.height - layout.value.height + currentTotal,
+          0,
+        );
+        const target = Math.min(scroll.value + effectiveDelta, maxScroll);
+
+        scrollToTarget(target);
+      }
+    },
+    [inverted, keyboardLiftBehavior],
+  );
+}
+
+export { useExtraContentPadding };
+export type { UseExtraContentPaddingOptions };