feat: useKeyboardState (#894)

## 📜 Description

Added new `useKeyboardState` hook.

## 💡 Motivation and Context

Turns out we don't have a pretty basic functionality - checking keyboard
state. So in this PR I'm adding `useKeyboardState` hook.

We already have `KeyboardController.state()` method, which can be used
inside callbacks. The new hook acts as a reactive function (i. e.
re-renders when data changes).

I've been thinking on how would be better implement this hook. Initial
considerations were:
- should we store data in context to make sure all dependant children
gets re-rendered simultaneously;
- should we use proxy/selectors to react on partial object changes and
re-render only then;

For both answers current answer is "no". Those are premature
optimizations and I'd like to start with something simple.

Later I can bring those optimizations in the codebase but for now we
simply make `.state()` reactive.

Also in this PR I made `state` always returning value. I think it'll be
annoying for devs to write `?.` everywhere, so starting from now this
method always returns state.

Closes
#893

## 📢 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 page about `useKeyboardState`;

### JS

- make `KeyboardController.state()` non-nullable;
- added `useKeyboardState` hook;
- added new mocks and new unit-tests.

## 🤔 How Has This Been Tested?

Tested in example app.

## 📸 Screenshots (if appropriate):


![image](https://github.com/user-attachments/assets/731ac502-9622-45de-b279-8bd116942068)

## 📝 Checklist

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

Author: kirillzyusko

FabricExample/__tests__/use-keyboard-state.spec.tsx

@@ -0,0 +1,18 @@
+import { renderHook } from "@testing-library/react-native";
+import { useKeyboardState } from "react-native-keyboard-controller";
+
+describe("`useKeyboardState` specification", () => {
+  it("should return mocked state", () => {
+    const { result } = renderHook(() => useKeyboardState());
+
+    expect(result.current).toStrictEqual({
+      isVisible: false,
+      height: 0,
+      duration: 0,
+      timestamp: 0,
+      target: 0,
+      type: "default",
+      appearance: "default",
+    });
+  });
+});

FabricExample/src/constants/screenNames.ts

@@ -23,4 +23,5 @@ export enum ScreenNames {
   BOTTOM_TAB_BAR = "BOTTOM_TAB_BAR",
   OVER_KEYBOARD_VIEW = "OVER_KEYBOARD_VIEW",
   IMAGE_GALLERY = "IMAGE_GALLERY",
+  USE_KEYBOARD_STATE = "USE_KEYBOARD_STATE",
 }

FabricExample/src/navigation/ExamplesStack/index.tsx

@@ -13,6 +13,7 @@ import InteractiveKeyboard from "../../screens/Examples/InteractiveKeyboard";
 import InteractiveKeyboardIOS from "../../screens/Examples/InteractiveKeyboardIOS";
 import KeyboardAnimation from "../../screens/Examples/KeyboardAnimation";
 import KeyboardAvoidingViewExample from "../../screens/Examples/KeyboardAvoidingView";
+import UseKeyboardState from "../../screens/Examples/KeyboardStateHook";
 import LottieAnimation from "../../screens/Examples/Lottie";
 import ModalExample from "../../screens/Examples/Modal";
 import NonUIProps from "../../screens/Examples/NonUIProps";
@@ -46,6 +47,7 @@ export type ExamplesStackParamList = {
   [ScreenNames.BOTTOM_TAB_BAR]: undefined;
   [ScreenNames.OVER_KEYBOARD_VIEW]: undefined;
   [ScreenNames.IMAGE_GALLERY]: undefined;
+  [ScreenNames.USE_KEYBOARD_STATE]: undefined;
 };
 
 const Stack = createStackNavigator<ExamplesStackParamList>();
@@ -115,6 +117,9 @@ const options = {
   [ScreenNames.IMAGE_GALLERY]: {
     title: "Image gallery",
   },
+  [ScreenNames.USE_KEYBOARD_STATE]: {
+    title: "useKeyboardState",
+  },
 };
 
 const ExamplesStack = () => (
@@ -224,6 +229,11 @@ const ExamplesStack = () => (
       name={ScreenNames.IMAGE_GALLERY}
       options={options[ScreenNames.IMAGE_GALLERY]}
     />
+    <Stack.Screen
+      component={UseKeyboardState}
+      name={ScreenNames.USE_KEYBOARD_STATE}
+      options={options[ScreenNames.USE_KEYBOARD_STATE]}
+    />
   </Stack.Navigator>
 );
 

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

@@ -0,0 +1,40 @@
+import React from "react";
+import { StyleSheet, Text, TextInput } from "react-native";
+import {
+  useKeyboardState,
+  useResizeMode,
+} from "react-native-keyboard-controller";
+
+const styles = StyleSheet.create({
+  input: {
+    height: 50,
+    width: "100%",
+    backgroundColor: "#3c3c3c",
+  },
+  text: {
+    color: "black",
+  },
+});
+
+export default function UseKeyboardState() {
+  useResizeMode();
+
+  const state = useKeyboardState();
+
+  return (
+    <>
+      <TextInput
+        keyboardAppearance="dark"
+        keyboardType="email-address"
+        style={styles.input}
+      />
+      <Text style={styles.text}>isVisible: {state.isVisible.toString()}</Text>
+      <Text style={styles.text}>height: {state.height}</Text>
+      <Text style={styles.text}>duration: {state.duration}</Text>
+      <Text style={styles.text}>timestamp: {state.timestamp}</Text>
+      <Text style={styles.text}>target: {state.target}</Text>
+      <Text style={styles.text}>type: {state.type}</Text>
+      <Text style={styles.text}>appearance: {state.appearance}</Text>
+    </>
+  );
+}

FabricExample/src/screens/Examples/Main/constants.ts

@@ -129,4 +129,10 @@ export const examples: Example[] = [
     info: ScreenNames.IMAGE_GALLERY,
     icons: "🖼️",
   },
+  {
+    title: "useKeyboardState",
+    testID: "use_keyboard_State",
+    info: ScreenNames.USE_KEYBOARD_STATE,
+    icons: "📝",
+  },
 ];

docs/docs/api/hooks/keyboard/use-keyboard-animation.md

@@ -6,6 +6,7 @@ keywords:
     react-native animated,
     react hook,
   ]
+sidebar_position: 1
 ---
 
 # useKeyboardAnimation

docs/docs/api/hooks/keyboard/use-keyboard-handler/index.mdx

@@ -11,6 +11,7 @@ keywords:
     worklet,
     react hook,
   ]
+sidebar_position: 3
 ---
 
 import CodeBlock from "@theme/CodeBlock";

docs/docs/api/hooks/keyboard/use-keyboard-state.mdx

@@ -0,0 +1,81 @@
+---
+keywords: [react-native-keyboard-controller, useKeyboardState, react hook]
+sidebar_position: 4
+---
+
+# useKeyboardState
+
+`useKeyboardState` is a hook which gives an access to current keyboard state.
+
+:::warning
+Use this hook only when you need to control `props` of views returned in JSX-markup. If you need to access the keyboard `state` in callbacks or event handlers then consider to use [KeyboardController.state()](../../keyboard-controller.md#state) method instead. This allows you to retrieve values as needed without triggering unnecessary re-renders.
+
+<div className="code-grid">
+<div className="code-block">
+
+```tsx title="✅ Recommended 👍"
+// use KeyboardController.state()
+
+<Button
+  onPress={() => {
+    const state = KeyboardController.state();
+    if (state.isVisible) {
+      // ...
+    }
+  }}
+>
+  Go to Next Page
+</Button>
+```
+
+</div>
+<div className="code-block">
+
+```tsx title="❌ Not recommended 🙅‍♂️"
+const { isVisible } = useKeyboardState();
+
+<Button
+  onPress={() => {
+    // don't consume state from hook
+    if (isVisible) {
+      // ...
+    }
+  }}
+>
+  Go to next Page
+</Button>;
+```
+
+</div>
+</div>
+
+:::
+
+## Data structure
+
+`useKeyboardState` returns a [`KeyboardState`](../../keyboard-controller.md#state) object.
+
+## Example
+
+```tsx
+import { View, Text, StyleSheet } from "react-native";
+import { useKeyboardState } from "react-native-keyboard-controller";
+
+const ShowcaseComponent = () => {
+  const { isVisible } = useKeyboardState();
+
+  return (
+    <View style={isVisible ? styles.highlighted : null}>
+      <Text>Address form</Text>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  highlighted: {
+    borderColor: "#0070D8",
+  },
+});
+```
+
+Also have a look on [example](https://github.com/kirillzyusko/react-native-keyboard-controller/tree/main/example) app for more comprehensive usage.

docs/docs/api/hooks/keyboard/use-reanimated-keyboard-animation.md

@@ -6,6 +6,7 @@ keywords:
     react-native-reanimated,
     react hook,
   ]
+sidebar_position: 2
 ---
 
 # useReanimatedKeyboardAnimation

docs/docs/api/keyboard-controller.md

@@ -93,11 +93,25 @@ if (KeyboardController.isVisible()) {
 ### `state`
 
 ```ts
-static state(): KeyboardEventData | null;
+static state(): KeyboardState;
 ```
 
 This method returns the last keyboard state. It returns `null` if keyboard was not shown in the app yet.
 
+The `KeyboardState` is represented by following structure:
+
+```ts
+type KeyboardState = {
+  isVisible: boolean;
+  height: number;
+  duration: number; // duration of the animation
+  timestamp: number; // timestamp of the event from native thread
+  target: number; // tag of the focused `TextInput`
+  type: string; // `keyboardType` property from focused `TextInput`
+  appearance: string; // `keyboardAppearance` property from focused `TextInput`
+};
+```
+
 ### `setFocusTo`
 
 ```ts