@react-native-ohos/react-native-keyboard-controller 1.16.8 → 1.17.0

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);
+};

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

@@ -0,0 +1,260 @@
+import { useSharedValue } from "react-native-reanimated";
+
+import { useKeyboardHandler } from "../../../hooks";
+import useScrollState from "../../hooks/useScrollState";
+
+import {
+  computeIOSContentOffset,
+  getEffectiveHeight,
+  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 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,
+    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,
+    size,
+    offset: scroll,
+    onLayout,
+    onContentSizeChange,
+  } = useScrollState(scrollViewRef);
+
+  useKeyboardHandler(
+    {
+      onStart: (e) => {
+        "worklet";
+
+        if (freeze.value) {
+          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,
+        );
+
+        // 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 (inverted) {
+            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(
+              0,
+              Math.min(scroll.value, maxScroll),
+            );
+          }
+
+          return;
+        }
+
+        // never mode: when keyboard shrinks, clamp to valid range
+        // to avoid ghost padding
+        if (
+          keyboardLiftBehavior === "never" &&
+          effective < padding.value &&
+          atEnd
+        ) {
+          padding.value = effective;
+          prevAbsorption.value = minimumPaddingAbsorbed;
+
+          if (inverted) {
+            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(
+              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 + prevScrollEffective
+          : scroll.value - prevScrollEffective;
+
+        padding.value = effective;
+        prevAbsorption.value = minimumPaddingAbsorbed;
+
+        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;
+        }
+
+        // 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,
+          scrollEffective,
+          size.value.height,
+          layout.value.height,
+          inverted,
+          actualTotalPadding,
+        );
+      },
+      onMove: () => {
+        "worklet";
+
+        // iOS doesn't need per-frame updates (contentOffset handles it)
+      },
+      onEnd: (e) => {
+        "worklet";
+
+        if (freeze.value) {
+          return;
+        }
+
+        const effective = getEffectiveHeight(
+          e.height,
+          targetKeyboardHeight.value,
+          offset,
+        );
+
+        padding.value = effective;
+      },
+    },
+    [inverted, keyboardLiftBehavior, offset, extraContentPadding],
+  );
+
+  return {
+    padding,
+    currentHeight,
+    contentOffsetY,
+    scroll,
+    layout,
+    size,
+    onLayout,
+    onContentSizeChange,
+  };
+}
+
+export { useChatKeyboard };