fix: useKeyboardState tweaks (#907)

## 📜 Description

Revisited some concepts of
`useKeyboardState`/`KeyboardController.state()` etc.

## 💡 Motivation and Context

After preparing a new release I went through the changes and realized,
that it would be better to take a step back and keep `isVisible`/`state`
decoupled but `useKeyboardState` should return data to all variables (i.
e. aggregate them).

## 📢 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
- mention animated hooks alternatives;

### JS

- don't include `isVisible` in `.state` method
- update types declaration to show that state doesn't return `null`
anymore;

## 🤔 How Has This Been Tested?

Tested via CI.

## 📝 Checklist

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

Author: kirillzyusko

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

@@ -5,21 +5,21 @@ sidebar_position: 4
 
 # useKeyboardState
 
-`useKeyboardState` is a hook which gives an access to current keyboard state.
+`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) method instead. This allows you to retrieve values as needed without triggering unnecessary re-renders.
+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.
 
 <div className="code-grid">
 <div className="code-block">
 
 ```tsx title="✅ Recommended 👍"
-// use KeyboardController.state()
+// use KeyboardController.isVisible()
 
 <Button
   onPress={() => {
-    const state = KeyboardController.state();
-    if (state.isVisible) {
+    // read value on demand
+    if (KeyboardController.isVisible()) {
       // ...
     }
   }}
@@ -51,9 +51,25 @@ const { isVisible } = useKeyboardState();
 
 :::
 
+:::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.
+:::
+
 ## Data structure
 
-`useKeyboardState` returns a [`KeyboardState`](../../keyboard-controller.md#state) object.
+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`
+};
+```
 
 ## Example
 

docs/docs/api/keyboard-controller.md

@@ -93,16 +93,15 @@ if (KeyboardController.isVisible()) {
 ### `state`
 
 ```ts
-static state(): KeyboardState;
+static state(): KeyboardEventData;
 ```
 
 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:
+The `KeyboardEventData` is represented by following structure:
 
 ```ts
-type KeyboardState = {
-  isVisible: boolean;
+type KeyboardEventData = {
   height: number;
   duration: number; // duration of the animation
   timestamp: number; // timestamp of the event from native thread

jest/index.js

@@ -29,15 +29,18 @@ const focusedInput = {
     set: jest.fn(),
   },
 };
-const state = {
-  isVisible: false,
+const lastKeyboardEvent = {
   height: 0,
   duration: 0,
   timestamp: 0,
   target: 0,
   type: "default",
   appearance: "default",
 };
+const state = {
+  ...lastKeyboardEvent,
+  isVisible: false,
+};
 
 const mock = {
   // hooks
@@ -65,7 +68,7 @@ const mock = {
     dismiss: jest.fn().mockReturnValue(Promise.resolve()),
     setFocusTo: jest.fn(),
     isVisible: jest.fn().mockReturnValue(false),
-    state: jest.fn().mockReturnValue(state),
+    state: jest.fn().mockReturnValue(lastKeyboardEvent),
   },
   AndroidSoftInputModes: {
     SOFT_INPUT_ADJUST_NOTHING: 48,

src/hooks/useKeyboardState/index.ts

@@ -3,24 +3,31 @@ import { useEffect, useState } from "react";
 import { KeyboardEvents } from "../../bindings";
 import { KeyboardController } from "../../module";
 
+import type { KeyboardState } from "../../types";
+
 const EVENTS = ["keyboardDidShow", "keyboardDidHide"] as const;
 
-export const useKeyboardState = () => {
-  const [state, setState] = useState(() => KeyboardController.state());
+const getLatestState = () => ({
+  ...KeyboardController.state(),
+  isVisible: KeyboardController.isVisible(),
+});
+
+export const useKeyboardState = (): KeyboardState => {
+  const [state, setState] = useState(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(KeyboardController.state()),
+        setState(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(KeyboardController.state());
+    setState(getLatestState);
 
     return () => {
       subscriptions.forEach((subscription) => subscription.remove());

src/module.ts

@@ -4,12 +4,10 @@ import type {
   DismissOptions,
   KeyboardControllerModule,
   KeyboardEventData,
-  KeyboardState,
 } from "./types";
 
 let isClosed = true;
-let lastState: KeyboardState = {
-  isVisible: false,
+let lastState: KeyboardEventData = {
   height: 0,
   duration: 0,
   timestamp: new Date().getTime(),
@@ -18,21 +16,14 @@ let lastState: KeyboardState = {
   appearance: "default",
 };
 
-const getKeyboardStateFromEvent = (event: KeyboardEventData): KeyboardState => {
-  return {
-    isVisible: event.height > 0,
-    ...event,
-  };
-};
-
 KeyboardEvents.addListener("keyboardDidHide", (e) => {
   isClosed = true;
-  lastState = getKeyboardStateFromEvent(e);
+  lastState = e;
 });
 
 KeyboardEvents.addListener("keyboardDidShow", (e) => {
   isClosed = false;
-  lastState = getKeyboardStateFromEvent(e);
+  lastState = e;
 });
 
 const dismiss = async (options?: DismissOptions): Promise<void> => {

src/types.ts

@@ -131,7 +131,7 @@ export type KeyboardControllerModule = {
   dismiss: (options?: DismissOptions) => Promise<void>;
   setFocusTo: (direction: Direction) => void;
   isVisible: () => boolean;
-  state: () => KeyboardEventData | null;
+  state: () => KeyboardEventData;
 };
 export type KeyboardControllerNativeModule = {
   // android only