feat: keyboard state selector (#998)

## 📜 Description

Added ability to pass selector to `useKeyboardState` hook to query only
necessary updates.

## 💡 Motivation and Context

The concept of selectors should be very familiar to many RN developers,
since it's used in `redux` and `zustand` packages. I was also thinking
about optimizing the amount of re-renders for this hook, but initially
I've been thinking of using proxy (similar to what `react-hook-form` is
doing). But such approach will introduce a lot of complexity, so I
decided to keep the codebase simple and efficient, so added a concept of
selectors.

Additionally I re-worked documnetation mainly focusing on:
- adding a sample how `useKeyboardAnimation` can be used as alternative;
- making warnings/tips shorter with corresponding references;
- adding the usage for selectors concept;
- use a real-world example with `useKeyboardState` (conditional
rendering instead of changing styles).

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

- allow to pass selectors to `useKeyboardState`;

### Docs

- make warning/tips shorter with corresponding links;
- added `useKeyboardState` vs `useKeyboardAnimation` code reference;
- mention how to use selectors;
- re-work example app to match real-world scenarios usage.

## 🤔 How Has This Been Tested?

Tested manually in example project.

## 📸 Screenshots (if appropriate):

|Dark theme|Light theme|
|------------|------------|

|![image](https://github.com/user-attachments/assets/11eb0c85-7d6d-43a5-9d81-0bfc072f9042)|![image](https://github.com/user-attachments/assets/693c7580-5780-4ab6-8799-43503684e075)|

## 📝 Checklist

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

Author: kirillzyusko

FabricExample/src/screens/Examples/LiquidKeyboard/ai-dark.png

@@ -1,9 +1,10 @@
 import React, { useEffect } from "react";
-import { Image, StyleSheet, TextInput } from "react-native";
+import { Image, StyleSheet, TextInput, useColorScheme } from "react-native";
 import {
   KeyboardBackgroundView,
   KeyboardEvents,
   KeyboardStickyView,
+  useKeyboardState,
 } from "react-native-keyboard-controller";
 import Reanimated, {
   interpolate,
@@ -16,13 +17,19 @@ import {
   useSafeAreaInsets,
 } from "react-native-safe-area-context";
 
+import DarkIcon from "./ai-dark.png";
+import LightIcon from "./ai.png";
+
 const ReanimatedBackgroundView = Reanimated.createAnimatedComponent(
   KeyboardBackgroundView,
 );
 
 const LiquidKeyboardExample = () => {
+  const scheme = useColorScheme();
+  const appearance = useKeyboardState((state) => state.appearance);
   const progress = useSharedValue(0);
   const { bottom } = useSafeAreaInsets();
+  const color = appearance === "default" ? scheme : appearance;
 
   useEffect(() => {
     progress.set(0);
@@ -98,7 +105,7 @@ const LiquidKeyboardExample = () => {
           ]}
         >
           <Image
-            source={require("./ai.png")}
+            source={color === "dark" ? LightIcon : DarkIcon}
             style={{ transform: [{ rotate: "-45deg" }], width: 20, height: 20 }}
           />
         </ReanimatedBackgroundView>

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

@@ -20,7 +20,42 @@ sidebar_position: 4
 `useKeyboardState` is a hook which gives an access to current keyboard state. This hook combines data from `KeyboardController.state()` and `KeyboardController.isVisible()` methods and makes it reactive (i. e. triggers a re-render when keyboard state/visibility has changed).
 
 :::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) or [KeyboardController.isVisible()](../../keyboard-controller.md#isvisible) methods instead. This allows you to retrieve values as needed without triggering unnecessary re-renders.
+Don’t use `state` from `useKeyboardState` inside event handlers. It will cause unnecessary re-renders. See [common pitfalls](#-common-pitfalls) section for more details and alternatives.
+:::
+
+:::tip
+Make sure that if you want to animate something based on keyboard presence then you've seen [optimize animation](#%EF%B8%8F-optimize-animations-with-native-threads) section.
+:::
+
+`useKeyboardState` allows you to pass a **selector** function to pick only the necessary part of the keyboard state data. This is a powerful technique to prevent unnecessary re-renders of your component when only a specific property of the keyboard state changes.
+
+```ts
+const appearance = useKeyboardState((state) => state.appearance);
+```
+
+In this example, your component will only re-render when the `appearance` property of the `KeyboardState` changes, rather than for any change in the entire state object.
+
+## Data structure
+
+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`
+};
+```
+
+## 🚫 Common Pitfalls
+
+### ⚠️ Avoid Unnecessary Re-renders
+
+If you need to access the keyboard `state` in callbacks or event handlers then consider to use [KeyboardController.state()](../../keyboard-controller.md#state) or [KeyboardController.isVisible()](../../keyboard-controller.md#isvisible) methods instead. This allows you to retrieve values as needed without triggering unnecessary re-renders.
 
 <div className="code-grid">
 <div className="code-block">
@@ -30,7 +65,7 @@ Use this hook only when you need to control `props` of views returned in JSX-mar
 
 <Button
   onPress={() => {
-    // read value on demand
+    // ✅ read value on demand
     if (KeyboardController.isVisible()) {
       // ...
     }
@@ -48,7 +83,7 @@ const { isVisible } = useKeyboardState();
 
 <Button
   onPress={() => {
-    // don't consume state from hook
+    // ❌ don't consume state from hook
     if (isVisible) {
       // ...
     }
@@ -61,42 +96,64 @@ const { isVisible } = useKeyboardState();
 </div>
 </div>
 
-:::
+### ⚡️ Optimize Animations with Native Threads
 
-:::tip
-Also make sure that if you need to change style based on keyboard presence then you are using corresponding [animated](./use-keyboard-animation) hooks to offload animation to a native thread and free up resources for JS thread.
-:::
+Don't use `useKeyboardState` for controlling styles, because:
 
-## Data structure
+- applying it directly to styles can lead to choppy animations;
+- it changes its values frequently making excessive re-renders on each keyboard state change.
 
-The `KeyboardState` is represented by following structure:
+If you need to change styles then you can use "animated" hooks such as [useKeyboardAnimation](./use-keyboard-animation), [useReanimatedKeyboardAnimation](./use-reanimated-keyboard-animation) or even [useKeyboardHandler](./use-keyboard-handler) to offload animation to a native thread and free up resources for JS thread.
 
-```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`
-};
+<div className="code-grid">
+<div className="code-block">
+
+```tsx title="✅ Recommended 👍"
+const { height } = useKeyboardAnimation();
+
+<Animated.View
+  style={{
+    width: "100%",
+    transform: [{ translateY: height }],
+  }}
+>
+  ...
+</Animated.View>;
 ```
 
+</div>
+<div className="code-block">
+
+```tsx title="❌ Not recommended 🙅‍♂️"
+const { height } = useKeyboardState();
+
+<View
+  style={{
+    width: "100%",
+    transform: [{ translateY: height }],
+  }}
+>
+  ...
+</View>;
+```
+
+</div>
+</div>
+
 ## Example
 
 ```tsx
 import { View, Text, StyleSheet } from "react-native";
 import { useKeyboardState } from "react-native-keyboard-controller";
 
 const ShowcaseComponent = () => {
-  const { isVisible } = useKeyboardState();
+  const isVisible = useKeyboardState((state) => state.isVisible);
 
-  return (
-    <View style={isVisible ? styles.highlighted : null}>
+  return isVisible ? (
+    <View style={styles.highlighted}>
       <Text>Address form</Text>
     </View>
-  );
+  ) : null;
 };
 
 const styles = StyleSheet.create({

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

@@ -1,9 +1,10 @@
 import React, { useEffect } from "react";
-import { Image, StyleSheet, TextInput } from "react-native";
+import { Image, StyleSheet, TextInput, useColorScheme } from "react-native";
 import {
   KeyboardBackgroundView,
   KeyboardEvents,
   KeyboardStickyView,
+  useKeyboardState,
 } from "react-native-keyboard-controller";
 import Reanimated, {
   interpolate,
@@ -16,13 +17,19 @@ import {
   useSafeAreaInsets,
 } from "react-native-safe-area-context";
 
+import DarkIcon from "./ai-dark.png";
+import LightIcon from "./ai.png";
+
 const ReanimatedBackgroundView = Reanimated.createAnimatedComponent(
   KeyboardBackgroundView,
 );
 
 const LiquidKeyboardExample = () => {
+  const scheme = useColorScheme();
+  const appearance = useKeyboardState((state) => state.appearance);
   const progress = useSharedValue(0);
   const { bottom } = useSafeAreaInsets();
+  const color = appearance === "default" ? scheme : appearance;
 
   useEffect(() => {
     progress.set(0);
@@ -98,7 +105,7 @@ const LiquidKeyboardExample = () => {
           ]}
         >
           <Image
-            source={require("./ai.png")}
+            source={color === "dark" ? LightIcon : DarkIcon}
             style={{ transform: [{ rotate: "-45deg" }], width: 20, height: 20 }}
           />
         </ReanimatedBackgroundView>

example/src/screens/Examples/LiquidKeyboard/ai-dark.png

@@ -51,7 +51,9 @@ const mock = {
   useGenericKeyboardHandler: jest.fn(),
   useKeyboardHandler: jest.fn(),
   useKeyboardContext: jest.fn().mockReturnValue(values),
-  useKeyboardState: jest.fn().mockReturnValue(state),
+  useKeyboardState: jest
+    .fn()
+    .mockImplementation((selector) => (selector ? selector(state) : state)),
   /// input
   useReanimatedFocusedInput: jest.fn().mockReturnValue(focusedInput),
   useFocusedInputHandler: jest.fn(),

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

@@ -12,11 +12,17 @@ const getLatestState = () => ({
   isVisible: KeyboardController.isVisible(),
 });
 
+type KeyboardStateSelector<T> = (state: KeyboardState) => T;
+
+const defaultSelector: KeyboardStateSelector<KeyboardState> = (state) => state;
+
 /**
  * React Hook that represents the current keyboard state on iOS and Android.
  * It tracks keyboard visibility, height, appearance, type and other properties.
  * This hook subscribes to keyboard events and updates the state reactively.
  *
+ * @template T - A type of the returned object from the `selector`.
+ * @param selector - A function that receives the current keyboard state and picks only necessary properties to avoid frequent re-renders.
  * @returns Object {@link KeyboardState|containing} keyboard state information.
  * @see {@link https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/hooks/keyboard/use-keyboard-state|Documentation} page for more details.
  * @example
@@ -32,27 +38,31 @@ const getLatestState = () => ({
  * }
  * ```
  */
-export const useKeyboardState = (): KeyboardState => {
-  const [state, setState] = useState(getLatestState);
+function useKeyboardState<T = KeyboardState>(
+  selector: KeyboardStateSelector<T> = defaultSelector as KeyboardStateSelector<T>,
+): T {
+  const [state, setState] = useState<T>(() => selector(getLatestState()));
 
   useEffect(() => {
     const subscriptions = EVENTS.map((event) =>
       KeyboardEvents.addListener(event, () =>
         // state will be updated by global listener first,
         // so we simply read it and don't derive data from the event
-        setState(getLatestState),
+        setState(selector(getLatestState())),
       ),
     );
 
     // we might have missed an update between reading a value in render and
     // `addListener` in this handler, so we set it here. If there was
     // no change, React will filter out this update as a no-op.
-    setState(getLatestState);
+    setState(selector(getLatestState()));
 
     return () => {
       subscriptions.forEach((subscription) => subscription.remove());
     };
   }, []);
 
   return state;
-};
+}
+
+export { useKeyboardState };