docs: better keyboardVerticalOffset for KeyboardAvoidingView explanation (#890)

## 📜 Description

Added a better explanation of what `keyboardVerticalOffset` does and
when to use it.

## 💡 Motivation and Context

Clearer documentation -> less bug reports 😎 

Closes
#887

## 📢 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 better explanation of `keyboardVerticalOffset property`;

## 🤔 How Has This Been Tested?

Tested via preview.

## 📸 Screenshots (if appropriate):

<img width="1003" alt="image"
src="https://github.com/user-attachments/assets/19a63ae9-305d-4828-be4a-a8af69444e11"
/>

## 📝 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-avoiding-view.mdx

@@ -132,4 +132,57 @@ A boolean prop indicating whether `KeyboardAvoidingView` is enabled or disabled.
 
 ### `keyboardVerticalOffset`
 
-This is the distance between the top of the user screen and the react native view, may be non-zero in some use cases. Default is `0`.
+This is the distance between the top of the user screen and the react native view This is particularly useful when there are fixed headers, navigation bars, or other UI elements at the top of the screen. Default is `0`.
+
+import KeyboardVerticalOffset from "@site/src/components/KeyboardVerticalOffset";
+
+<details>
+  <summary>When to use `keyboardVerticalOffset`?</summary>
+
+You should use `keyboardVerticalOffset` in the following scenarios:
+
+- **Navigation Bars / Headers** - If your screen is inside a `Stack.Navigator` from `react-navigation`, the header height should be compensated using `keyboardVerticalOffset`:
+
+```tsx
+import { useHeaderHeight } from "@react-navigation/elements";
+import { KeyboardAvoidingView } from "react-native-keyboard-controller";
+
+const MyScreen = () => {
+  const headerHeight = useHeaderHeight();
+
+  return (
+    <KeyboardAvoidingView
+      behavior="padding"
+      keyboardVerticalOffset={headerHeight}
+    >
+      <TextInput placeholder="Type here..." />
+    </KeyboardAvoidingView>
+  );
+};
+```
+
+- **Custom Toolbars or Fixed Elements at the Top** - If your app has a fixed toolbar, status bar, or other UI elements at the top, you should offset accordingly.
+
+- **Modal Screens with Different Layouts** - When using `KeyboardAvoidingView` inside a `Modal`, you may need to manually define the vertical offset to account for the modal’s positioning.
+
+Below shown a visual representation of `keyboardVerticalOffset`:
+
+<KeyboardVerticalOffset />
+
+:::warning Translucent `StatusBar`
+If you are using translucent `StatusBar` on Android, then `StatusBar` padding gets handled by `react-navigation` automatically and it will include safe-area padding in `useHeaderHeight` (i. e. `StatusBar` height will be included in the returned value and it will match iOS behavior).
+
+If you are not using translucent `StatusBar`, then you need to include `StatusBar` height yourself:
+
+```tsx
+const headerHeight = useHeaderHeight() + (StatusBar.currentHeight ?? 0);
+```
+
+<blockquote>
+  `StatusBar.currentHeight` is Android-only prop so you can use `?? 0` and don't
+  write platform-specific code using `Platform.OS` or `Platform.select`.
+</blockquote>
+
+:::
+
+</details>

docs/src/components/KeyboardVerticalOffset/index.tsx

@@ -0,0 +1,19 @@
+import { useColorMode } from "@docusaurus/theme-common";
+import React from "react";
+
+import KeyboardVerticalOffsetDark from "./kvo-dark.svg";
+import KeyboardVerticalOffsetLight from "./kvo-light.svg";
+
+export default function KeyboardVerticalOffsetIcon() {
+  const { colorMode } = useColorMode();
+
+  return (
+    <div className="center">
+      {colorMode === "dark" ? (
+        <KeyboardVerticalOffsetDark className="svg" />
+      ) : (
+        <KeyboardVerticalOffsetLight className="svg" />
+      )}
+    </div>
+  );
+}