feat: docs, e2e tests, updated example app

FabricExample/src/screens/Examples/AwareScrollView/index.tsx

@@ -1,15 +1,39 @@
-import React from "react";
+import React, { useEffect, useState } from "react";
+import { Text } from "react-native";
 import { KeyboardAwareScrollView } from "react-native-keyboard-controller";
 
 import TextInput from "../../../components/TextInput";
 
 import { styles } from "./styles";
 
-export default function AwareScrollView() {
+import type { ExamplesStackParamList } from "../../../navigation/ExamplesStack";
+import type { StackScreenProps } from "@react-navigation/stack";
+
+type Props = StackScreenProps<ExamplesStackParamList>;
+
+export default function AwareScrollView({ navigation }: Props) {
+  const [disableScrollOnKeyboardHide, setDisableScrollOnKeyboardHide] =
+    useState(false);
+
+  useEffect(() => {
+    navigation.setOptions({
+      headerRight: () => (
+        <Text
+          style={styles.header}
+          onPress={() => setDisableScrollOnKeyboardHide((value) => !value)}
+          testID="disable_scroll_on_keyboard_hide"
+        >
+          {`Back scroll: ${!disableScrollOnKeyboardHide ? "true" : "false"}`}
+        </Text>
+      ),
+    });
+  }, [disableScrollOnKeyboardHide]);
+
   return (
     <KeyboardAwareScrollView
       testID="aware_scroll_view_container"
       bottomOffset={50}
+      disableScrollOnKeyboardHide={disableScrollOnKeyboardHide}
       style={styles.container}
       contentContainerStyle={styles.content}
     >

FabricExample/src/screens/Examples/AwareScrollView/styles.ts

@@ -7,4 +7,8 @@ export const styles = StyleSheet.create({
   content: {
     paddingTop: 50,
   },
+  header: {
+    color: "black",
+    paddingRight: 12,
+  },
 });

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

@@ -65,7 +65,11 @@ Inherits [ScrollView Props](https://reactnative.dev/docs/scrollview#props).
 
 ### `bottomOffset`
 
-The distance between keyboard and focused `TextInput` when keyboard is shown.
+The distance between keyboard and focused `TextInput` when keyboard is shown. Default is `0`.
+
+### `disableScrollOnKeyboardHide`
+
+Prevents automatic scrolling of the `ScrollView` when the keyboard gets hidden, maintaining the current screen position. Default is `false`.
 
 ## Example
 

docs/versioned_docs/version-1.10.0/api/components/keyboard-aware-scroll-view.mdx

@@ -65,7 +65,11 @@ Inherits [ScrollView Props](https://reactnative.dev/docs/scrollview#props).
 
 ### `bottomOffset`
 
-The distance between keyboard and focused `TextInput` when keyboard is shown.
+The distance between keyboard and focused `TextInput` when keyboard is shown. Default is `0`.
+
+### `disableScrollOnKeyboardHide`
+
+Prevents automatic scrolling of the `ScrollView` when the keyboard gets hidden, maintaining the current screen position. Default is `false`.
 
 ## Example
 

e2e/kit/002-aware-scroll-view.e2e.ts

@@ -12,6 +12,11 @@ import setDemoMode from "./utils/setDemoMode";
 
 const BLINKING_CURSOR = 0.35;
 
+const closeKeyboard = async () => {
+  // tap outside to close a keyboard
+  await tap("aware_scroll_view_container", { x: 0, y: 100 });
+};
+
 describe("AwareScrollView test cases", () => {
   beforeAll(async () => {
     await setDemoMode();
@@ -62,13 +67,30 @@ describe("AwareScrollView test cases", () => {
   });
 
   it("should scroll back when keyboard dismissed", async () => {
-    // tap outside to close a keyboard
-    await tap("aware_scroll_view_container", { x: 0, y: 100 });
+    await closeKeyboard();
     await waitForExpect(async () => {
       await expectBitmapsToBeEqual(
         "AwareScrollViewKeyboardClosed",
         BLINKING_CURSOR,
       );
     });
   });
+
+  it("shouldn't scroll back when keyboard dismissed if such behavior intentionally disabled", async () => {
+    await waitAndTap("disable_scroll_on_keyboard_hide");
+    await waitAndTap("TextInput#5");
+    await waitForExpect(async () => {
+      await expectBitmapsToBeEqual(
+        "AwareScrollViewSecondInputFocused",
+        BLINKING_CURSOR,
+      );
+    });
+    await closeKeyboard();
+    await waitForExpect(async () => {
+      await expectBitmapsToBeEqual(
+        "AwareScrollViewKeyboardClosedWithoutBackScroll",
+        BLINKING_CURSOR,
+      );
+    });
+  });
 });

example/src/screens/Examples/AwareScrollView/index.tsx

@@ -1,14 +1,34 @@
-import React, { useState } from "react";
-import { Button } from "react-native";
+import React, { useEffect, useState } from "react";
+import { Text } from "react-native";
 import { KeyboardAwareScrollView } from "react-native-keyboard-controller";
 
 import TextInput from "../../../components/TextInput";
 
 import { styles } from "./styles";
 
-export default function AwareScrollView() {
+import type { ExamplesStackParamList } from "../../../navigation/ExamplesStack";
+import type { StackScreenProps } from "@react-navigation/stack";
+
+type Props = StackScreenProps<ExamplesStackParamList>;
+
+export default function AwareScrollView({ navigation }: Props) {
   const [disableScrollOnKeyboardHide, setDisableScrollOnKeyboardHide] =
     useState(false);
+
+  useEffect(() => {
+    navigation.setOptions({
+      headerRight: () => (
+        <Text
+          style={styles.header}
+          onPress={() => setDisableScrollOnKeyboardHide((value) => !value)}
+          testID="disable_scroll_on_keyboard_hide"
+        >
+          {`Back scroll: ${!disableScrollOnKeyboardHide ? "true" : "false"}`}
+        </Text>
+      ),
+    });
+  }, [disableScrollOnKeyboardHide]);
+
   return (
     <KeyboardAwareScrollView
       testID="aware_scroll_view_container"
@@ -17,14 +37,6 @@ export default function AwareScrollView() {
       style={styles.container}
       contentContainerStyle={styles.content}
     >
-      <Button
-        title={`Set Disable Scroll on Close to: ${
-          disableScrollOnKeyboardHide ? "Off" : "On"
-        }`}
-        onPress={() =>
-          setDisableScrollOnKeyboardHide(!disableScrollOnKeyboardHide)
-        }
-      />
       {new Array(10).fill(0).map((_, i) => (
         <TextInput
           key={i}

example/src/screens/Examples/AwareScrollView/styles.ts

@@ -7,4 +7,8 @@ export const styles = StyleSheet.create({
   content: {
     paddingTop: 50,
   },
+  header: {
+    color: "black",
+    paddingRight: 12,
+  },
 });

src/components/KeyboardAwareScrollView/index.tsx

@@ -23,7 +23,9 @@ import type { ScrollViewProps } from "react-native";
 import type { FocusedInputLayoutChangedEvent } from "react-native-keyboard-controller";
 
 type KeyboardAwareScrollViewProps = {
+  /** The distance between keyboard and focused `TextInput` when keyboard is shown. Default is `0`. */
   bottomOffset?: number;
+  /** Prevents automatic scrolling of the `ScrollView` when the keyboard gets hidden, maintaining the current screen position. Default is `false`. */
   disableScrollOnKeyboardHide?: boolean;
 } & ScrollViewProps;