react-native-keyboard-controller 1.17.1 → 1.17.2

package/src/hooks/index.ts

@@ -8,6 +8,20 @@ import type { AnimatedContext, ReanimatedContext } from "../context";
 import type { FocusedInputHandler, KeyboardHandler } from "../types";
 import type { DependencyList } from "react";
 
+/**
+ * Hook that sets the Android soft input mode to adjust resize on mount and
+ * restores default mode on unmount. This ensures the keyboard behavior is consistent
+ * on all Android versions.
+ *
+ * @see {@link https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/keyboard-controller#setinputmode-|Documentation} page for more details.
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   useResizeMode();
+ *   return <View />;
+ * }
+ * ```
+ */
 export const useResizeMode = () => {
   useEffect(() => {
     KeyboardController.setInputMode(
@@ -18,6 +32,20 @@ export const useResizeMode = () => {
   }, []);
 };
 
+/**
+ * Hook that provides animated (`height`/`progress`) values for tracking keyboard movement.
+ * Automatically sets the resize mode for Android.
+ *
+ * @returns Object {@link AnimatedContext|containing} animated values for keyboard movement.
+ * @see {@link https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/hooks/keyboard/use-keyboard-animation|Documentation} page for more details.
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { height, progress } = useKeyboardAnimation();
+ *   return <Animated.View style={{ transform: [{ translateY: height }] }} />;
+ * }
+ * ```
+ */
 export const useKeyboardAnimation = (): AnimatedContext => {
   useResizeMode();
   const context = useKeyboardContext();
@@ -25,6 +53,20 @@ export const useKeyboardAnimation = (): AnimatedContext => {
   return context.animated;
 };
 
+/**
+ * Hook that provides reanimated (`height`/`progress`) values for tracking keyboard movement.
+ * Automatically sets the resize mode for Android.
+ *
+ * @returns Object {@link ReanimatedContext|containing} reanimated values for keyboard movement.
+ * @see {@link https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/hooks/keyboard/use-reanimated-keyboard-animation|Documentation} page for more details.
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { height, progress } = useReanimatedKeyboardAnimation();
+ *   return <Reanimated.View style={{ transform: [{ translateY: height }] }} />;
+ * }
+ * ```
+ */
 export const useReanimatedKeyboardAnimation = (): ReanimatedContext => {
   useResizeMode();
   const context = useKeyboardContext();
@@ -32,6 +74,37 @@ export const useReanimatedKeyboardAnimation = (): ReanimatedContext => {
   return context.reanimated;
 };
 
+/**
+ * An alternative to {@link useKeyboardHandler} that doesn't set resize mode on mount. If your
+ * app already uses `adjustResize`, then you can use this hook instead of `useKeyboardHandler`.
+ *
+ * @param handler - Object containing keyboard event handlers.
+ * @param [deps] - Dependencies array for the effect.
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const height = useSharedValue(0);
+ *   const progress = useSharedValue(0);
+ *
+ *   useGenericKeyboardHandler({
+ *     onMove: (e) => {
+ *       "worklet";
+ *
+ *       height.value = e.height;
+ *       progress.value = e.progress;
+ *     },
+ *     onEnd: (e) => {
+ *       "worklet";
+ *
+ *       height.value = e.height;
+ *       progress.value = e.progress;
+ *     },
+ *   }, []);
+ *
+ *   return <Reanimated.View style={{ height: height }] }} />;
+ * }
+ * ```
+ */
 export function useGenericKeyboardHandler(
   handler: KeyboardHandler,
   deps?: DependencyList,
@@ -45,6 +118,37 @@ export function useGenericKeyboardHandler(
   }, deps);
 }
 
+/**
+ * Hook that gives an access to each aspect of keyboard movement with workletized `onStart`/`onMove`/`onInteractive`/`onEnd` handlers.
+ *
+ * @param handler - Object containing keyboard event handlers.
+ * @param [deps] - Dependencies array for the effect.
+ * @see {@link https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/hooks/keyboard/use-keyboard-handler|Documentation} page for more details.
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const height = useSharedValue(0);
+ *   const progress = useSharedValue(0);
+ *
+ *   useKeyboardHandler({
+ *     onMove: (e) => {
+ *       "worklet";
+ *
+ *       height.value = e.height;
+ *       progress.value = e.progress;
+ *     },
+ *     onEnd: (e) => {
+ *       "worklet";
+ *
+ *       height.value = e.height;
+ *       progress.value = e.progress;
+ *     },
+ *   }, []);
+ *
+ *   return <Reanimated.View style={{ height: height }] }} />;
+ * }
+ * ```
+ */
 export function useKeyboardHandler(
   handler: KeyboardHandler,
   deps?: DependencyList,
@@ -53,18 +157,71 @@ export function useKeyboardHandler(
   useGenericKeyboardHandler(handler, deps);
 }
 
+/**
+ * Hook for controlling keyboard controller module.
+ * Allows to disable/enable it and check the actual state (whether it's enabled or not).
+ * When disabled it fallbacks to default android keyboard handling and stops tracking all
+ * the events that are exposed from this library.
+ *
+ * @property {Function} setEnabled - Function to enable/disable keyboard handling.
+ * @property {boolean} enabled - Current enabled state.
+ * @returns Object containing keyboard control functions and state.
+ * @see {@link https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/hooks/module/use-keyboard-controller|Documentation} page for more details.
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { setEnabled, enabled } = useKeyboardController();
+ *   return (
+ *     <Button
+ *       title={enabled ? 'Disable' : 'Enable'}
+ *       onPress={() => setEnabled(!enabled)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function useKeyboardController() {
   const context = useKeyboardContext();
 
   return { setEnabled: context.setEnabled, enabled: context.enabled };
 }
 
+/**
+ * Hook that provides access to the layout of the currently focused input.
+ *
+ * @returns Object containing reanimated values for focused input.
+ * @see {@link https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/hooks/input/use-reanimated-focused-input|Documentation} page for more details.
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { input } = useReanimatedFocusedInput();
+ *   return <Reanimated.View style={{ height: input.value?.layout.height }} />;
+ * }
+ * ```
+ */
 export function useReanimatedFocusedInput() {
   const context = useKeyboardContext();
 
   return { input: context.layout };
 }
 
+/**
+ * Hook for handling focused input events, such as changes of selection, text etc.
+ *
+ * @param handler - Object containing focused input event handlers.
+ * @param [deps] - Dependencies array for the effect.
+ * @see {@link https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/hooks/input/use-focused-input-handler|Documentation} page for more details.
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   useFocusedInputHandler({
+ *     onChangeText: (e) => console.log('Text changed:', e.text),
+ *     onSelectionChange: (e) => console.log('Selection changed:', e.selection)
+ *   });
+ *   return <View />;
+ * }
+ * ```
+ */
 export function useFocusedInputHandler(
   handler: FocusedInputHandler,
   deps?: DependencyList,

package/src/hooks/useKeyboardState/index.ts

@@ -12,6 +12,26 @@ const getLatestState = () => ({
   isVisible: KeyboardController.isVisible(),
 });
 
+/**
+ * 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.
+ *
+ * @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
+ * ```tsx
+ * function MyComponent() {
+ *   const { isVisible, height } = useKeyboardState();
+ *   return (
+ *     <View>
+ *       <Text>Keyboard is {isVisible ? 'visible' : 'hidden'}</Text>
+ *       <Text>Keyboard height: {height}</Text>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
 export const useKeyboardState = (): KeyboardState => {
   const [state, setState] = useState(getLatestState);
 

package/src/internal.ts

@@ -7,6 +7,20 @@ import { findNodeHandle } from "./utils/findNodeHandle";
 type EventHandler = (event: never) => void;
 type ComponentOrHandle = Parameters<typeof findNodeHandle>[0];
 
+/**
+ * An internal hook that helps to register workletized event handlers.
+ *
+ * @param map - Map of event handlers and their names.
+ * @param viewTagRef - Ref to the view that produces events.
+ * @returns A function that registers supplied event handlers.
+ * @example
+ * ```ts
+ * const setKeyboardHandlers = useEventHandlerRegistration<KeyboardHandler>(
+ *     keyboardEventsMap,
+ *     viewTagRef,
+ * );
+ * ```
+ */
 export function useEventHandlerRegistration<
   H extends Partial<Record<string, EventHandler>>,
 >(
@@ -68,7 +82,14 @@ export function useEventHandlerRegistration<
  * and therefore consumes less memory. We can not use a variant from
  * RN, since this library supports earlier versions of RN.
  *
+ * @param initialValue - Initial value of the animated value (numeric).
+ * @param config - Additional {@link Animated.AnimatedConfig|configuration} for the animated value.
+ * @returns Properly memoized {@link Animated.Value|Animated} value.
  * @see https://github.com/facebook/react-native/commit/e22217fe8b9455e32695f88ca835e11442b0a937
+ * @example
+ * ```ts
+ * const progress = useAnimatedValue(0);
+ * ```
  */
 export function useAnimatedValue(
   initialValue: number,

package/src/module.ts

@@ -47,6 +47,9 @@ const dismiss = async (options?: DismissOptions): Promise<void> => {
 const isVisible = () => !isClosed;
 const state = () => lastState;
 
+/**
+ * KeyboardController module. Helps to perform imperative actions/checks with keyboard.
+ */
 export const KeyboardController: KeyboardControllerModule = {
   setDefaultMode: KeyboardControllerNative.setDefaultMode,
   setInputMode: KeyboardControllerNative.setInputMode,

package/src/monkey-patch.android.ts

@@ -20,12 +20,9 @@ const ModifiedNativeAndroidManager = {
   setTranslucent: (translucent: boolean): void => {
     RCTStatusBarManagerCompat.setTranslucent(translucent);
   },
-  /**
-   *  - statusBarStyles can be:
-   *    - 'default'
-   *    - 'dark-content'
-   */
-  setStyle: (statusBarStyle?: string): void => {
+  setStyle: (
+    statusBarStyle?: "default" | "dark-content" | "light-content",
+  ): void => {
     RCTStatusBarManagerCompat.setStyle(statusBarStyle);
   },
   setHidden: (hidden: boolean): void => {

package/src/{types.ts → types/hooks.ts}

@@ -1,44 +1,60 @@
-import type { PropsWithChildren } from "react";
-import type {
-  EmitterSubscription,
-  NativeSyntheticEvent,
-  TextInputProps,
-  ViewProps,
-} from "react-native";
+import type { NativeSyntheticEvent, ViewProps } from "react-native";
 
 // DirectEventHandler events declaration
 export type NativeEvent = {
+  /** A value between `0` and `1` indicating keyboard position, where `0` means keyboard is closed and `1` means keyboard is fully visible. */
   progress: number;
+  /** Height of the keyboard. */
   height: number;
+  /** Duration of the keyboard animation. */
   duration: number;
+  /** Tag of the focused `TextInput`. */
   target: number;
 };
 export type FocusedInputLayoutChangedEvent = {
+  /** Tag of the focused `TextInput`. */
   target: number;
+  /** Tag of the parent `ScrollView`. */
   parentScrollViewTarget: number;
   layout: {
+    /** X coordinate of the focused `TextInput`. */
     x: number;
+    /** Y coordinate of the focused `TextInput`. */
     y: number;
+    /** Width of the focused `TextInput`. */
     width: number;
+    /** Height of the focused `TextInput`. */
     height: number;
+    /** X coordinate of the focused `TextInput` relative to the screen. */
     absoluteX: number;
+    /** Y coordinate of the focused `TextInput` relative to the screen. */
     absoluteY: number;
   };
 };
 export type FocusedInputTextChangedEvent = {
+  /** Text that user typed in the focused `TextInput`. */
   text: string;
 };
 export type FocusedInputSelectionChangedEvent = {
+  /** Tag of the focused `TextInput`. */
   target: number;
   selection: {
+    /** Start of the selection. Represents top-left point of rectangle. */
     start: {
+      /** X coordinate of the selection start (relative to the `TextInput`). */
       x: number;
+      /** Y coordinate of the selection start (relative to the `TextInput`). */
       y: number;
+      /** The start of selection. */
       position: number;
     };
+    /** End of the selection. Represents bottom-right point of rectangle. */
     end: {
+      /** X coordinate of the selection end (relative to the `TextInput`). */
       x: number;
+      /** Y coordinate of the selection end (relative to the `TextInput`). */
       y: number;
+      /** The end of selection. */
       position: number;
     };
   };
@@ -93,104 +109,6 @@ export type KeyboardControllerProps = {
   enabled?: boolean;
 } & ViewProps;
 
-export type KeyboardGestureAreaProps = {
-  interpolator?: "ios" | "linear";
-  /**
-   * Whether to allow to show a keyboard from dismissed state by swipe up.
-   * Default to `false`.
-   */
-  showOnSwipeUp?: boolean;
-  /**
-   * Whether to allow to control a keyboard by gestures. The strategy how
-   * it should be controlled is determined by `interpolator` property.
-   * Defaults to `true`.
-   */
-  enableSwipeToDismiss?: boolean;
-  /**
-   * Extra distance to the keyboard.
-   */
-  offset?: number;
-  /**
-   * A corresponding `nativeID` value from the corresponding `TextInput`.
-   */
-  textInputNativeID?: string;
-} & ViewProps;
-export type OverKeyboardViewProps = PropsWithChildren<{
-  visible: boolean;
-}>;
-
-export type Direction = "next" | "prev" | "current";
-export type DismissOptions = {
-  keepFocus: boolean;
-};
-export type KeyboardControllerModule = {
-  // android only
-  setDefaultMode: () => void;
-  setInputMode: (mode: number) => void;
-  // all platforms
-  dismiss: (options?: DismissOptions) => Promise<void>;
-  setFocusTo: (direction: Direction) => void;
-  isVisible: () => boolean;
-  state: () => KeyboardEventData;
-};
-export type KeyboardControllerNativeModule = {
-  // android only
-  setDefaultMode: () => void;
-  setInputMode: (mode: number) => void;
-  // all platforms
-  dismiss: (keepFocus: boolean) => void;
-  setFocusTo: (direction: Direction) => void;
-  // native event module stuff
-  addListener: (eventName: string) => void;
-  removeListeners: (count: number) => void;
-};
-
-// Event module declarations
-export type KeyboardControllerEvents =
-  | "keyboardWillShow"
-  | "keyboardDidShow"
-  | "keyboardWillHide"
-  | "keyboardDidHide";
-export type KeyboardEventData = {
-  height: number;
-  duration: number;
-  timestamp: number;
-  target: number;
-  type: NonNullable<TextInputProps["keyboardType"]>;
-  appearance: NonNullable<TextInputProps["keyboardAppearance"]>;
-};
-export type KeyboardState = {
-  isVisible: boolean;
-} & KeyboardEventData;
-export type KeyboardEventsModule = {
-  addListener: (
-    name: KeyboardControllerEvents,
-    cb: (e: KeyboardEventData) => void,
-  ) => EmitterSubscription;
-};
-export type FocusedInputAvailableEvents = "focusDidSet";
-export type FocusedInputEventData = {
-  current: number;
-  count: number;
-};
-export type FocusedInputEventsModule = {
-  addListener: (
-    name: FocusedInputAvailableEvents,
-    cb: (e: FocusedInputEventData) => void,
-  ) => EmitterSubscription;
-};
-export type WindowDimensionsAvailableEvents = "windowDidResize";
-export type WindowDimensionsEventData = {
-  width: number;
-  height: number;
-};
-export type WindowDimensionsEventsModule = {
-  addListener: (
-    name: WindowDimensionsAvailableEvents,
-    cb: (e: WindowDimensionsEventData) => void,
-  ) => EmitterSubscription;
-};
-
 // reanimated hook declaration
 export type KeyboardHandlerHook<TContext, Event> = (
   handlers: {
@@ -232,14 +150,63 @@ export type FocusedInputSelectionHandlerHook<TContext, Event> = (
 // package types
 export type Handlers<T> = Record<string, T | undefined>;
 export type KeyboardHandler = Partial<{
+  /**
+   * A callback that gets invoked when keyboard starts its movement.
+   * The event contains DESTINATION values.
+   *
+   * @example
+   * ```ts
+   * onStart: (e) => {
+   *   "worklet";
+   *
+   *   const willKeyboardAppear = e.progress === 1;
+   * }
+   * ```
+   */
   onStart: (e: NativeEvent) => void;
+  /**
+   * A callback that gets involved every frame when keyboard changes its position.
+   *
+   * @example
+   * ```ts
+   * onMove: (e) => {
+   *   "worklet";
+   *
+   *   const keyboardHeight = e.height;
+   * }
+   */
   onMove: (e: NativeEvent) => void;
+  /**
+   * A callback that gets invoked when keyboard finished its movement.
+   *
+   * @example
+   * ```ts
+   * onEnd: (e) => {
+   *   "worklet";
+   *
+   *   const isKeyboardShown = e.progress === 1;
+   * }
+   * ```
+   */
   onEnd: (e: NativeEvent) => void;
+  /**
+   * A callback that gets invoked every frame when keyboard changes its position due to interactive dismissal.
+   *
+   * @example
+   * ```ts
+   * onInteractive: (e) => {
+   *   "worklet";
+   *
+   *   const keyboardHeight = e.height;
+   * }
+   */
   onInteractive: (e: NativeEvent) => void;
 }>;
 export type KeyboardHandlers = Handlers<KeyboardHandler>;
 export type FocusedInputHandler = Partial<{
+  /** A callback that gets invoked every time when the text changes in focused input. */
   onChangeText: (e: FocusedInputTextChangedEvent) => void;
+  /** A callback that gets invoked every time when the selection (cursor) coordinates change in focused input. */
   onSelectionChange: (e: FocusedInputSelectionChangedEvent) => void;
 }>;
 export type FocusedInputHandlers = Handlers<FocusedInputHandler>;

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export * from "./hooks";
+export * from "./views";
+export * from "./module";
+export * from "./internal";

package/src/types/internal.ts

@@ -0,0 +1,24 @@
+import type { EmitterSubscription } from "react-native";
+
+export type FocusedInputAvailableEvents = "focusDidSet";
+export type FocusedInputEventData = {
+  current: number;
+  count: number;
+};
+export type FocusedInputEventsModule = {
+  addListener: (
+    name: FocusedInputAvailableEvents,
+    cb: (e: FocusedInputEventData) => void,
+  ) => EmitterSubscription;
+};
+export type WindowDimensionsAvailableEvents = "windowDidResize";
+export type WindowDimensionsEventData = {
+  width: number;
+  height: number;
+};
+export type WindowDimensionsEventsModule = {
+  addListener: (
+    name: WindowDimensionsAvailableEvents,
+    cb: (e: WindowDimensionsEventData) => void,
+  ) => EmitterSubscription;
+};

package/src/types/module.ts

@@ -0,0 +1,105 @@
+import type { EmitterSubscription, TextInputProps } from "react-native";
+
+// Event module declarations
+export type KeyboardControllerEvents =
+  | "keyboardWillShow"
+  | "keyboardDidShow"
+  | "keyboardWillHide"
+  | "keyboardDidHide";
+export type KeyboardEventData = {
+  /** Height of the keyboard. */
+  height: number;
+  /** Duration of the keyboard animation. */
+  duration: number;
+  /** Timestamp of the last keyboard event. */
+  timestamp: number;
+  /** Tag of the focused `TextInput`. */
+  target: number;
+  /** `keyboardType` property from focused `TextInput`. */
+  type: NonNullable<TextInputProps["keyboardType"]>;
+  /** Keyboard appearance. Can be one of `default`, `dark` or `light`. */
+  appearance: NonNullable<TextInputProps["keyboardAppearance"]>;
+};
+/**
+ * An object that represent current keyboard state.
+ */
+export type KeyboardState = {
+  /** Whether the keyboard is currently visible. */
+  isVisible: boolean;
+} & KeyboardEventData;
+export type KeyboardEventsModule = {
+  /**
+   * The `addListener` function connects a JavaScript function to an identified native
+   * keyboard notification event.
+   *
+   * This function then returns the reference to the listener.
+   *
+   * `name` is the string that identifies the event you're listening for. This
+   * can be any of the following:
+   *
+   * - `keyboardWillShow`;
+   * - `keyboardDidShow`;
+   * - `keyboardWillHide`;
+   * - `keyboardDidHide`.
+   */
+  addListener: (
+    name: KeyboardControllerEvents,
+    cb: (e: KeyboardEventData) => void,
+  ) => EmitterSubscription;
+};
+export type Direction = "next" | "prev" | "current";
+export type DismissOptions = {
+  /**
+   * A boolean property indicating whether focus should be kept on the input after dismissing the keyboard. Default is `false`.
+   */
+  keepFocus: boolean;
+};
+export type KeyboardControllerModule = {
+  // android only
+  /**
+   * Sets default `windowSoftInputMode` (the one that declared in `AndroidManifest.xml`).
+   *
+   * @see {@link https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/keyboard-controller#setdefaultmode-|docs} page for more details.
+   */
+  setDefaultMode: () => void;
+  /**
+   * Changes `windowSoftInputMode` on Android. @see AndroidSoftInputModes for all possible values and {@link https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/keyboard-controller#setinputmode-|docs} page for more details.
+   */
+  setInputMode: (mode: number) => void;
+  // all platforms
+  /**
+   * Dismisses the active keyboard. Removes a focus by default, but allows to pass `{keepFocus: true}` to keep focus.
+   *
+   * @see {@link https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/keyboard-controller#dismiss|docs} page for more details.
+   */
+  dismiss: (options?: DismissOptions) => Promise<void>;
+  /**
+   * Moves focus to the specified direction (`next`, `prev` or `current` to restore a focus).
+   *
+   * @see {@link https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/keyboard-controller#setfocusto|docs} page for more details.
+   */
+  setFocusTo: (direction: Direction) => void;
+  /**
+   * Whether the keyboard is fully visible.
+   *
+   * @see {@link https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/keyboard-controller#isvisible|docs} page for more details.
+   */
+  isVisible: () => boolean;
+  /**
+   * Method that returns current keyboard state.
+   *
+   * @see {@link https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/keyboard-controller#state|docs} page for more details.
+   */
+  state: () => KeyboardEventData;
+};
+export type KeyboardControllerNativeModule = {
+  // android only
+  setDefaultMode: () => void;
+  setInputMode: (mode: number) => void;
+  // all platforms
+  dismiss: (keepFocus: boolean) => void;
+  setFocusTo: (direction: Direction) => void;
+  // native event module stuff
+  addListener: (eventName: string) => void;
+  removeListeners: (count: number) => void;
+};