feat: add onContentInsetChange callback (#1445)

## 📜 Description

Added `onContentInsetChange` callback.

## 💡 Motivation and Context

Modifying `contentInsets` changes scrollable area. In `react-native`
this event propagates through `onScroll` event. In JS I can not modify
it (this event) just because we have so many variation in terms of how
to intercept the `onScroll` event (Animated, Reanimated, plain JS
callback) so that for example for `Animated` with native driver I can
not simply modify event structure, because I'll emit event from JS but
this event is not possible to send to mobile.

So I decided to add separate `onContentInsetChange` event. At the moment
this callback will be needed in `LegendList` to implement accurate
`scrollToEnd` and other functions that depends on precise scroll
coordinates.

## 📢 Changelog

<!-- High level overview of important changes -->
<!-- For example: fixed status bar manipulation; added new types
declarations; -->
<!-- If your changes don't affect one of platform/language below - then
remove this platform/language -->

### JS

- added `onContentInsetChange` callback;

## 🤔 How Has This Been Tested?

Tested manually.

## 📝 Checklist

- [x] CI successfully passed
- [x] I added new mocks and corresponding unit-tests if library API was
changed

Author: kirillzyusko

docs/docs/api/components/keyboard-chat-scroll-view.mdx

@@ -168,6 +168,22 @@ To fix this, you must either:
 Without one of these solutions, users won't be able to scroll or interact with content in the minimum padding area.
 :::
 
+### `onContentInsetChange`
+
+A callback fired whenever the effective content inset changes — i.e. the static [`contentInset`](https://reactnative.dev/docs/scrollview#contentinset) prop combined with the dynamic keyboard-driven padding (`keyboardPadding + extraContentPadding`, or `blankSpace` when it dominates).
+
+```ts
+type Insets = { top: number; bottom: number; left: number; right: number };
+
+onContentInsetChange?: (insets: Insets) => void;
+```
+
+The callback is invoked on every animation frame during the keyboard transition (and once for any non-animated change to the static `contentInset` prop).
+
+:::tip When to use it?
+On **Android**, the synthetic content inset is _not_ included in the native `onScroll` event payload (because the inset is simulated at the React Native layer rather than reported by the native `ScrollView`). Use `onContentInsetChange` to track the current inset alongside scroll offsets.
+:::
+
 ## Usage with virtualized lists
 
 `KeyboardChatScrollView` doesn't ship with built-in wrappers for third-party virtualized list libraries, but since all of them (`FlatList`, `FlashList`, `LegendList`) accept a custom scroll component, integration is straightforward.

docs/versioned_docs/version-1.21.0/api/components/keyboard-chat-scroll-view.mdx

@@ -168,6 +168,22 @@ To fix this, you must either:
 Without one of these solutions, users won't be able to scroll or interact with content in the minimum padding area.
 :::
 
+### `onContentInsetChange`
+
+A callback fired whenever the effective content inset changes — i.e. the static [`contentInset`](https://reactnative.dev/docs/scrollview#contentinset) prop combined with the dynamic keyboard-driven padding (`keyboardPadding + extraContentPadding`, or `blankSpace` when it dominates).
+
+```ts
+type Insets = { top: number; bottom: number; left: number; right: number };
+
+onContentInsetChange?: (insets: Insets) => void;
+```
+
+The callback is invoked on every animation frame during the keyboard transition (and once for any non-animated change to the static `contentInset` prop).
+
+:::tip When to use it?
+On **Android**, the synthetic content inset is _not_ included in the native `onScroll` event payload (because the inset is simulated at the React Native layer rather than reported by the native `ScrollView`). Use `onContentInsetChange` to track the current inset alongside scroll offsets.
+:::
+
 ## Usage with virtualized lists
 
 `KeyboardChatScrollView` doesn't ship with built-in wrappers for third-party virtualized list libraries, but since all of them (`FlatList`, `FlashList`, `LegendList`) accept a custom scroll component, integration is straightforward.

src/components/KeyboardChatScrollView/types.ts

@@ -1,4 +1,7 @@
-import type { AnimatedScrollViewComponent } from "../ScrollViewWithBottomPadding";
+import type {
+  AnimatedScrollViewComponent,
+  ScrollViewContentInsets,
+} from "../ScrollViewWithBottomPadding";
 import type { KeyboardLiftBehavior } from "./useChatKeyboard/types";
 import type { ScrollViewProps } from "react-native";
 import type { SharedValue } from "react-native-reanimated";
@@ -87,4 +90,13 @@ export type KeyboardChatScrollViewProps = {
    * Default is `undefined` (equivalent to `0` — no minimum floor).
    */
   blankSpace?: SharedValue<number>;
+  /**
+   * Fires whenever the effective content inset changes — the static `contentInset`
+   * prop combined with the dynamic keyboard-driven padding.
+   *
+   * Useful on Android, where the synthetic content inset is not reflected in the native
+   * `onScroll` event payload. Consumers such as virtualized lists computing their own
+   * `scrollToEnd` target can use this to track the current inset alongside scroll offsets.
+   */
+  onContentInsetChange?: (insets: ScrollViewContentInsets) => void;
 } & ScrollViewProps;

src/components/ScrollViewWithBottomPadding/index.tsx

@@ -1,7 +1,10 @@
 import React, { forwardRef } from "react";
 import { Platform } from "react-native";
 import Reanimated, {
+  runOnJS,
   useAnimatedProps,
+  useAnimatedReaction,
+  useDerivedValue,
   useSharedValue,
 } from "react-native-reanimated";
 
@@ -26,6 +29,13 @@ export type AnimatedScrollViewComponent = React.ForwardRefExoticComponent<
   AnimatedScrollViewProps & React.RefAttributes<Reanimated.ScrollView>
 >;
 
+export type ScrollViewContentInsets = {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+};
+
 type ScrollViewWithBottomPaddingProps = {
   ScrollViewComponent: AnimatedScrollViewComponent;
   children?: React.ReactNode;
@@ -36,6 +46,12 @@ type ScrollViewWithBottomPaddingProps = {
   /** Absolute Y content offset (iOS only, for KeyboardChatScrollView). */
   contentOffsetY?: SharedValue<number>;
   applyWorkaroundForContentInsetHitTestBug?: boolean;
+  /**
+   * Fires whenever the effective content inset changes (combines the static `contentInset`
+   * prop with the dynamic keyboard-driven padding). Useful on Android where the synthetic
+   * inset is not reflected in `onScroll` events.
+   */
+  onContentInsetChange?: (insets: ScrollViewContentInsets) => void;
 } & ScrollViewProps;
 
 const ScrollViewWithBottomPadding = forwardRef<
@@ -52,18 +68,60 @@ const ScrollViewWithBottomPadding = forwardRef<
       inverted,
       contentOffsetY,
       applyWorkaroundForContentInsetHitTestBug,
+      onContentInsetChange,
       children,
       ...rest
     },
     ref,
   ) => {
     const prevContentOffsetY = useSharedValue<number | null>(null);
 
+    const insets = useDerivedValue(() => {
+      const dynamicTop = inverted ? bottomPadding.value : 0;
+      const dynamicBottom = !inverted ? bottomPadding.value : 0;
+
+      return {
+        dynamic: {
+          top: dynamicTop,
+          bottom: dynamicBottom,
+        },
+        effective: {
+          top: dynamicTop + (contentInset?.top || 0),
+          bottom: dynamicBottom + (contentInset?.bottom || 0),
+          left: contentInset?.left || 0,
+          right: contentInset?.right || 0,
+        } as ScrollViewContentInsets,
+      };
+    }, [
+      inverted,
+      contentInset?.top,
+      contentInset?.bottom,
+      contentInset?.left,
+      contentInset?.right,
+    ]);
+
+    useAnimatedReaction(
+      () => insets.value.effective,
+      (current, previous) => {
+        if (!onContentInsetChange) {
+          return;
+        }
+        if (
+          previous &&
+          current.top === previous.top &&
+          current.bottom === previous.bottom &&
+          current.left === previous.left &&
+          current.right === previous.right
+        ) {
+          return;
+        }
+        runOnJS(onContentInsetChange)(current);
+      },
+      [onContentInsetChange],
+    );
+
     const animatedProps = useAnimatedProps(() => {
-      const insetTop = inverted ? bottomPadding.value : 0;
-      const insetBottom = !inverted ? bottomPadding.value : 0;
-      const bottom = insetBottom + (contentInset?.bottom || 0);
-      const top = insetTop + (contentInset?.top || 0);
+      const { dynamic, effective } = insets.value;
 
       const indicatorPadding = scrollIndicatorPadding ?? bottomPadding;
       const indicatorTop =
@@ -75,21 +133,16 @@ const ScrollViewWithBottomPadding = forwardRef<
 
       const result: Record<string, unknown> = {
         // iOS prop
-        contentInset: {
-          bottom: bottom,
-          top: top,
-          right: contentInset?.right,
-          left: contentInset?.left,
-        },
+        contentInset: effective,
         scrollIndicatorInsets: {
           bottom: indicatorBottom,
           top: indicatorTop,
           right: scrollIndicatorInsets?.right,
           left: scrollIndicatorInsets?.left,
         },
         // Android prop
-        contentInsetBottom: insetBottom,
-        contentInsetTop: insetTop,
+        contentInsetBottom: dynamic.bottom,
+        contentInsetTop: dynamic.top,
       };
 
       if (contentOffsetY) {
@@ -104,10 +157,6 @@ const ScrollViewWithBottomPadding = forwardRef<
 
       return result;
     }, [
-      contentInset?.bottom,
-      contentInset?.top,
-      contentInset?.right,
-      contentInset?.left,
       scrollIndicatorInsets?.bottom,
       scrollIndicatorInsets?.top,
       scrollIndicatorInsets?.right,