feat: useAnimatedKeyboard compat layer (#1220)

## 📜 Description

Added `useAnimatedKeyboard` hook (same as in reanimated, but based on
keyboard-controller API).

## 💡 Motivation and Context

Based on
software-mansion/react-native-reanimated#8622 we
want to deliver as smooth as possible way to migrate from a deprecated
API. In many cases people don't want to copy/paste code and manage it on
their own, so in this PR I'm adding a proposed compat layer directly in
the core of `react-native-keyboard-controller`. Using this compat layer
devs will just need:
- install this lib;
- change the import to use new hook;

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

- added `useAnimatedKeyboard`/`KeyboardState`
- renamed `KeyboardState` to `IKeyboardState` since it conflicts with
reanimated name;

## 🤔 How Has This Been Tested?

Tested via e2e tests that I didn't break anything accidentally.

## 📸 Screenshots (if appropriate):

<img width="633" height="311" alt="image"
src="https://github.com/user-attachments/assets/9b3039d6-d59e-4f14-96ff-d8fee0b12447"
/>

## 📝 Checklist

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

Author: kirillzyusko

src/compat.ts

@@ -0,0 +1,61 @@
+import { useSharedValue } from "react-native-reanimated";
+
+import { useKeyboardHandler } from "./hooks";
+
+export const KeyboardState = {
+  UNKNOWN: 0,
+  OPENING: 1,
+  OPEN: 2,
+  CLOSING: 3,
+  CLOSED: 4,
+};
+
+/**
+ * A compatibility layer for migration from https://docs.swmansion.com/react-native-reanimated/docs/device/useAnimatedKeyboard.
+ *
+ * @returns An object containing `height` and `state` properties represented as `SharedValue<number>`.
+ * @example
+ * ```ts
+ * import { useAnimatedKeyboard, useAnimatedStyle } from 'react-native-keyboard-controller';
+ *
+ * export default function App() {
+ *   const keyboard = useAnimatedKeyboard();
+ *
+ *   const animatedStyles = useAnimatedStyle(() => ({
+ *     transform: [{ translateY: -keyboard.height.value }],
+ *   }));
+ * }
+ */
+export const useAnimatedKeyboard = () => {
+  const height = useSharedValue(0);
+  const state = useSharedValue(KeyboardState.UNKNOWN);
+
+  useKeyboardHandler(
+    {
+      onStart: (e) => {
+        "worklet";
+
+        state.set(e.height > 0 ? KeyboardState.OPENING : KeyboardState.CLOSING);
+      },
+      onMove: (e) => {
+        "worklet";
+
+        height.set(e.height);
+      },
+      onInteractive: (e) => {
+        "worklet";
+
+        height.set(e.height);
+      },
+      onEnd: (e) => {
+        "worklet";
+
+        state.set(e.height > 0 ? KeyboardState.OPEN : KeyboardState.CLOSED);
+        height.set(e.height);
+      },
+    },
+    [],
+  );
+
+  return { height, state };
+};

src/hooks/useKeyboardState/index.ts

@@ -3,7 +3,7 @@ import { useEffect, useState } from "react";
 import { KeyboardEvents } from "../../bindings";
 import { KeyboardController } from "../../module";
 
-import type { KeyboardState } from "../../types";
+import type { IKeyboardState } from "../../types";
 
 const EVENTS = ["keyboardDidShow", "keyboardDidHide"] as const;
 
@@ -12,9 +12,9 @@ const getLatestState = () => ({
   isVisible: KeyboardController.isVisible(),
 });
 
-type KeyboardStateSelector<T> = (state: KeyboardState) => T;
+type KeyboardStateSelector<T> = (state: IKeyboardState) => T;
 
-const defaultSelector: KeyboardStateSelector<KeyboardState> = (state) => state;
+const defaultSelector: KeyboardStateSelector<IKeyboardState> = (state) => state;
 
 /**
  * React Hook that represents the current keyboard state on iOS and Android.
@@ -40,7 +40,7 @@ const defaultSelector: KeyboardStateSelector<KeyboardState> = (state) => state;
  * }
  * ```
  */
-function useKeyboardState<T = KeyboardState>(
+function useKeyboardState<T = IKeyboardState>(
   selector: KeyboardStateSelector<T> = defaultSelector as KeyboardStateSelector<T>,
 ): T {
   const [state, setState] = useState<T>(() => selector(getLatestState()));

src/index.ts

@@ -5,6 +5,7 @@ export * from "./hooks";
 export * from "./constants";
 export * from "./module";
 export * from "./types";
+export * from "./compat";
 
 export {
   KeyboardAvoidingView,

src/types/module.ts

@@ -23,7 +23,7 @@ export type KeyboardEventData = {
 /**
  * An object that represent current keyboard state.
  */
-export type KeyboardState = {
+export type IKeyboardState = {
   /** Whether the keyboard is currently visible. */
   isVisible: boolean;
 } & KeyboardEventData;