docs: KeyboardChatScrollView fixes after devs feedback (#1322)

## 📜 Description

Updated documentation after reviewing own changes and gathering feedback
from developers.

## 💡 Motivation and Context

Current documentation is good, but lacks few important aspects (such as
enabling reanimated feature flags). To avoid spamming with new issues
and improve dev experience I added more content.

## 📢 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 -->

### Docs

- added troubleshooting section with enabling reanimated feature flag;
- strict typing of `ref` from `VirtualizedScrollView`;
- make video default size so content is not jumping while page is
laoding
- add video to "building chat app" page.

## 🤔 How Has This Been Tested?

Tested via preview and locally on `localhost:3000`.

## 📸 Screenshots (if appropriate):

<img width="1350" height="1157" alt="image"
src="https://github.com/user-attachments/assets/0d8f4625-18ee-40c3-a38f-2bc8c78f636a"
/>

## 📝 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

@@ -4,7 +4,10 @@
 
 import Video from "@site/src/components/Video";
 
-<Video src="/video/keyboard-chat-scroll-view/always.mov" width={35} />
+<Video
+  src="/video/keyboard-chat-scroll-view/always.mov"
+  style={{ height: "40vh" }}
+/>
 
 ## Props
 
@@ -43,25 +46,37 @@ Controls how the chat content responds when the keyboard appears. Defaults to `"
 
 Content always lifts with the keyboard, keeping the bottom messages visible **regardless** of the current scroll position. This is the most common chat app behavior, used by **Telegram**, **WhatsApp**, and others.
 
-<Video src="/video/keyboard-chat-scroll-view/always.mov" width={25} />
+<Video
+  src="/video/keyboard-chat-scroll-view/always.mov"
+  style={{ height: "40vh" }}
+/>
 
 #### `whenAtEnd`
 
 Content lifts only when the scroll view is **at the end** (i.e., the last message is visible or near the bottom). If the user has scrolled up to read older messages, the keyboard won't push the content around. This matches the **ChatGPT** mobile app behavior.
 
-<Video src="/video/keyboard-chat-scroll-view/when-at-end.mov" width={25} />
+<Video
+  src="/video/keyboard-chat-scroll-view/when-at-end.mov"
+  style={{ height: "40vh" }}
+/>
 
 #### `persistent`
 
 Content lifts when the keyboard appears, but **does not drop back** when the keyboard hides. The scroll position stays where it was pushed to. This matches the **Claude** mobile app behavior.
 
-<Video src="/video/keyboard-chat-scroll-view/persistent.mp4" width={25} />
+<Video
+  src="/video/keyboard-chat-scroll-view/persistent.mp4"
+  style={{ height: "40vh" }}
+/>
 
 #### `never`
 
 Content never moves in response to the keyboard. The keyboard simply overlaps the chat. This matches the **Perplexity** app behavior.
 
-<Video src="/video/keyboard-chat-scroll-view/never.mov" width={25} />
+<Video
+  src="/video/keyboard-chat-scroll-view/never.mov"
+  style={{ height: "40vh" }}
+/>
 
 ### `offset`
 
@@ -76,12 +91,18 @@ This is useful when the input is not at the very bottom of the screen — for ex
 First, create a wrapper component:
 
 ```tsx title="VirtualizedListScrollView.tsx"
-import { forwardRef } from "react";
+import React, { forwardRef } from "react";
 import { KeyboardChatScrollView } from "react-native-keyboard-controller";
 
 import type { ScrollViewProps } from "react-native";
+import type { KeyboardChatScrollViewProps } from "react-native-keyboard-controller";
+
+type Ref = React.ElementRef<typeof KeyboardChatScrollView>;
 
-const VirtualizedListScrollView = forwardRef((props: ScrollViewProps, ref) => {
+const VirtualizedListScrollView = forwardRef<
+  Ref,
+  ScrollViewProps & KeyboardChatScrollViewProps
+>((props, ref) => {
   return (
     <KeyboardChatScrollView
       ref={ref}
@@ -180,3 +201,29 @@ On iOS we change the [`contentOffset`](https://reactnative.dev/docs/scrollview#c
 #### Android
 
 On Android we adjust the scroll position inside the [`onMove`](../hooks/keyboard/use-keyboard-handler#onmove) handler via the [`scrollTo`](https://docs.swmansion.com/react-native-reanimated/docs/scroll/scrollTo/) method on the UI thread from a worklet.
+
+## Troubleshooting
+
+### Reanimated feature flag
+
+`KeyboardChatScrollView` relies on a Reanimated commit hook internally. If you're using **Reanimated < 4.3.0**, you need to enable the [`USE_COMMIT_HOOK_ONLY_FOR_REACT_COMMITS`](https://docs.swmansion.com/react-native-reanimated/docs/guides/feature-flags/#use_commit_hook_only_for_react_commits) feature flag in your `package.json`:
+
+```json
+{
+  "reanimated": {
+    "staticFeatureFlags": {
+      "USE_COMMIT_HOOK_ONLY_FOR_REACT_COMMITS": true
+    }
+  }
+}
+```
+
+After adding this, run `pod install` (iOS) and rebuild the app.
+
+:::tip Reanimated 4.3.0+ relevance
+If you're on **Reanimated 4.3.0+**, this flag is enabled by default — no extra configuration needed.
+:::
+
+:::info What it affects?
+If you don't enable this flag you'll see de-synchronized keyboard animation on Android/Fabric architecture.
+:::

docs/docs/guides/building-chat-app.mdx

@@ -15,6 +15,13 @@ keywords:
 
 Keyboard handling in chat applications has always been one of the trickiest problems in mobile development — even on native platforms. Chat apps push keyboard interactions to their limits: interactive dismissal, content repositioning, smooth transitions between the keyboard and custom input views, and all of it at 120 FPS. Getting this right requires deep integration between the keyboard, scroll views, and layout systems — far more than a general-purpose component can offer.
 
+import Video from "@site/src/components/Video";
+
+<Video
+  src="/video/keyboard-chat-scroll-view/always.mov"
+  style={{ height: "40vh", marginBottom: 20 }}
+/>
+
 ## Why general-purpose components fall short
 
 You might be tempted to reach for `KeyboardAvoidingView` or `KeyboardAwareScrollView` to handle keyboard interactions in a chat app. While these components work well for forms, settings screens, and other straightforward layouts, they weren't designed for the unique demands of a chat interface.
@@ -199,15 +206,21 @@ For production chat apps you'll likely use a virtualized list (`FlatList`, `Flas
 Create a wrapper that passes `KeyboardChatScrollView` props down:
 
 ```tsx title="VirtualizedListScrollView.tsx"
-import { forwardRef } from "react";
+import React, { forwardRef } from "react";
 import { KeyboardChatScrollView } from "react-native-keyboard-controller";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 
 import type { ScrollViewProps } from "react-native";
+import type { KeyboardChatScrollViewProps } from "react-native-keyboard-controller";
+
+type Ref = React.ElementRef<typeof KeyboardChatScrollView>;
 
 const BOTTOM_OFFSET = 8; // distance from safe area to input
 
-const VirtualizedListScrollView = forwardRef((props: ScrollViewProps, ref) => {
+const VirtualizedListScrollView = forwardRef<
+  Ref,
+  ScrollViewProps & KeyboardChatScrollViewProps
+>((props, ref) => {
   const { bottom } = useSafeAreaInsets();
 
   return (
@@ -272,26 +285,27 @@ const renderScrollComponent = useCallback(
 If your list uses the `inverted` prop (the standard pattern for chat lists where newest messages appear at the bottom), make sure to pass `inverted` to `KeyboardChatScrollView` as well:
 
 ```tsx title="VirtualizedListScrollView.tsx"
-const VirtualizedListScrollView = forwardRef(
-  ({ inverted, ...props }: ScrollViewProps & { inverted?: boolean }, ref) => {
-    return (
-      <KeyboardChatScrollView
-        ref={ref}
-        // add-new-code
-        inverted={inverted}
-        {...props}
-      />
-    );
-  },
-);
+const VirtualizedListScrollView = forwardRef<
+  Ref,
+  ScrollViewProps & KeyboardChatScrollViewProps
+>(({ inverted, ...props }, ref) => {
+  return (
+    <KeyboardChatScrollView
+      ref={ref}
+      // add-new-code
+      inverted={inverted}
+      {...props}
+    />
+  );
+});
 ```
 
 ## Complete example
 
 Here is a complete chat screen that ties together all the pieces — `KeyboardChatScrollView` with a `FlatList`, interactive dismissal, sticky input, and safe area handling:
 
 ```tsx
-import { useCallback, useRef, useState } from "react";
+import React, { forwardRef, useCallback, useRef, useState } from "react";
 import {
   FlatList,
   StyleSheet,
@@ -310,11 +324,18 @@ import {
   useSafeAreaInsets,
 } from "react-native-safe-area-context";
 
+import type { KeyboardChatScrollViewProps } from "react-native-keyboard-controller";
+
+type Ref = React.ElementRef<typeof KeyboardChatScrollView>;
+
 const MARGIN = 8;
 const INPUT_HEIGHT = 42;
 
 // Wrapper for virtualized lists
-const ChatScrollView = forwardRef((props: ScrollViewProps, ref) => {
+const ChatScrollView = forwardRef<
+  Ref,
+  ScrollViewProps & KeyboardChatScrollViewProps
+>((props, ref) => {
   const { bottom } = useSafeAreaInsets();
 
   return (
@@ -411,3 +432,9 @@ Or play with the code in live mode directly in the browser:
 ## API reference
 
 For the full list of props and design principles, see the [`KeyboardChatScrollView` API reference](../api/components/keyboard-chat-scroll-view).
+
+## Troubleshooting
+
+:::danger Check troubleshooting section first
+If you encounter any issues with `KeyboardChatScrollView`, please check the [Troubleshooting section](../api/components/keyboard-chat-scroll-view#troubleshooting) first before reporting a bug. If you're still having trouble, feel free to [open an issue](https://github.com/kirillzyusko/react-native-keyboard-controller/issues/new) on GitHub.
+:::