react-native-universal-keyboard-aware-scrollview 1.0.0

package/src/hooks/useKeyboard.ts

@@ -0,0 +1,360 @@
+import { useEffect, useState, useCallback, useRef } from 'react';
+import { Platform, Keyboard, LayoutAnimation, UIManager } from 'react-native';
+import {
+  UniversalKeyboardModule,
+  KeyboardEventEmitter,
+  isNativeModuleAvailable,
+} from '../NativeModule';
+import type { KeyboardEvent } from '../types';
+
+// Enable LayoutAnimation on Android
+if (
+  Platform.OS === 'android' &&
+  UIManager.setLayoutAnimationEnabledExperimental
+) {
+  UIManager.setLayoutAnimationEnabledExperimental(true);
+}
+
+/**
+ * Options for useKeyboard hook
+ */
+export interface UseKeyboardOptions {
+  /** Enable keyboard handling on Android (default: true) */
+  enableOnAndroid?: boolean;
+  /** Enable keyboard handling on iOS (default: true) */
+  enableOnIOS?: boolean;
+  /** Whether to use native module events (default: true on both platforms) */
+  useNativeEvents?: boolean;
+  /** Whether to animate height changes (default: true) */
+  animated?: boolean;
+  /** Callback when keyboard will show (iOS only) */
+  onKeyboardWillShow?: (event: KeyboardEvent) => void;
+  /** Callback when keyboard will hide (iOS only) */
+  onKeyboardWillHide?: (event: KeyboardEvent) => void;
+  /** Callback when keyboard did show */
+  onKeyboardDidShow?: (event: KeyboardEvent) => void;
+  /** Callback when keyboard did hide */
+  onKeyboardDidHide?: (event: KeyboardEvent) => void;
+  /** Callback when keyboard height changes */
+  onKeyboardHeightChange?: (height: number) => void;
+}
+
+/**
+ * Return type for useKeyboard hook
+ */
+export interface UseKeyboardReturn {
+  /** Current keyboard height in points/dp */
+  keyboardHeight: number;
+  /** Whether the keyboard is currently visible */
+  isKeyboardVisible: boolean;
+  /** Whether the keyboard is currently animating */
+  isAnimating: boolean;
+  /** Dismiss the keyboard programmatically */
+  dismissKeyboard: () => Promise<void>;
+  /** Screen height in points/dp */
+  screenHeight: number;
+  /** Animation duration in ms when keyboard shows/hides */
+  animationDuration: number;
+  /** Safe area bottom inset (iOS only) */
+  safeAreaBottom: number;
+}
+
+/**
+ * useKeyboard - A hook for tracking keyboard state and height
+ *
+ * This hook provides reliable keyboard detection that works in:
+ * - Normal React Native screens
+ * - React Native Modal components
+ * - BottomSheet components
+ * - Any overlay/presentation scenarios
+ *
+ * @example
+ * ```tsx
+ * const { keyboardHeight, isKeyboardVisible, dismissKeyboard } = useKeyboard();
+ *
+ * return (
+ *   <View style={{ paddingBottom: keyboardHeight }}>
+ *     <TextInput placeholder="Type here..." />
+ *     <Button onPress={dismissKeyboard} title="Dismiss" />
+ *   </View>
+ * );
+ * ```
+ */
+export function useKeyboard(options: UseKeyboardOptions = {}): UseKeyboardReturn {
+  const {
+    enableOnAndroid = true,
+    enableOnIOS = true,
+    useNativeEvents = true,
+    animated = true,
+    onKeyboardWillShow,
+    onKeyboardWillHide,
+    onKeyboardDidShow,
+    onKeyboardDidHide,
+    onKeyboardHeightChange,
+  } = options;
+
+  const [keyboardState, setKeyboardState] = useState({
+    keyboardHeight: 0,
+    isKeyboardVisible: false,
+    isAnimating: false,
+    screenHeight: 0,
+    animationDuration: 0,
+    safeAreaBottom: 0,
+  });
+
+  const isEnabled =
+    (Platform.OS === 'android' && enableOnAndroid) ||
+    (Platform.OS === 'ios' && enableOnIOS);
+
+  const nativeModuleActive = useRef(false);
+
+  // Handle keyboard height change
+  const handleKeyboardHeightChange = useCallback(
+    (event: KeyboardEvent) => {
+      if (!isEnabled) return;
+
+      const height = event.height ?? 0;
+      const duration = event.duration ?? 250;
+
+      if (animated && duration > 0) {
+        LayoutAnimation.configureNext({
+          duration: duration,
+          update: {
+            type: LayoutAnimation.Types.keyboard,
+            property: LayoutAnimation.Properties.opacity,
+          },
+        });
+      }
+
+      setKeyboardState((prev) => ({
+        ...prev,
+        keyboardHeight: height,
+        isKeyboardVisible: height > 0,
+        screenHeight: event.screenHeight ?? prev.screenHeight,
+        animationDuration: duration,
+        safeAreaBottom: event.safeAreaBottom ?? prev.safeAreaBottom,
+        isAnimating: false,
+      }));
+
+      onKeyboardHeightChange?.(height);
+    },
+    [isEnabled, animated, onKeyboardHeightChange]
+  );
+
+  // Handle keyboard will show
+  const handleKeyboardWillShow = useCallback(
+    (event: KeyboardEvent) => {
+      if (!isEnabled) return;
+
+      setKeyboardState((prev) => ({
+        ...prev,
+        isAnimating: true,
+      }));
+
+      onKeyboardWillShow?.(event);
+    },
+    [isEnabled, onKeyboardWillShow]
+  );
+
+  // Handle keyboard will hide
+  const handleKeyboardWillHide = useCallback(
+    (event: KeyboardEvent) => {
+      if (!isEnabled) return;
+
+      setKeyboardState((prev) => ({
+        ...prev,
+        isAnimating: true,
+      }));
+
+      onKeyboardWillHide?.(event);
+    },
+    [isEnabled, onKeyboardWillHide]
+  );
+
+  // Handle keyboard did show
+  const handleKeyboardDidShow = useCallback(
+    (event: KeyboardEvent) => {
+      if (!isEnabled) return;
+
+      setKeyboardState((prev) => ({
+        ...prev,
+        keyboardHeight: event.height,
+        isKeyboardVisible: true,
+        isAnimating: false,
+        screenHeight: event.screenHeight ?? prev.screenHeight,
+        safeAreaBottom: event.safeAreaBottom ?? prev.safeAreaBottom,
+      }));
+
+      onKeyboardDidShow?.(event);
+    },
+    [isEnabled, onKeyboardDidShow]
+  );
+
+  // Handle keyboard did hide
+  const handleKeyboardDidHide = useCallback(
+    (event: KeyboardEvent) => {
+      if (!isEnabled) return;
+
+      setKeyboardState((prev) => ({
+        ...prev,
+        keyboardHeight: 0,
+        isKeyboardVisible: false,
+        isAnimating: false,
+      }));
+
+      onKeyboardDidHide?.(event);
+    },
+    [isEnabled, onKeyboardDidHide]
+  );
+
+  // Dismiss keyboard
+  const dismissKeyboard = useCallback(async () => {
+    if (isNativeModuleAvailable()) {
+      try {
+        await UniversalKeyboardModule.dismissKeyboard();
+      } catch {
+        // Fall back to RN Keyboard API
+        Keyboard.dismiss();
+      }
+    } else {
+      Keyboard.dismiss();
+    }
+  }, []);
+
+  // Set up event listeners
+  useEffect(() => {
+    if (!isEnabled) return;
+
+    const subscriptions: (() => void)[] = [];
+
+    // Use native module events if available and enabled
+    if (useNativeEvents && isNativeModuleAvailable() && KeyboardEventEmitter) {
+      // Start listening on native side
+      UniversalKeyboardModule.startListening()
+        .then(() => {
+          nativeModuleActive.current = true;
+        })
+        .catch((error) => {
+          console.warn('[useKeyboard] Failed to start native listener:', error);
+        });
+
+      // Subscribe to native events
+      subscriptions.push(
+        (() => {
+          const sub = KeyboardEventEmitter.addListener(
+            'keyboardHeightChanged',
+            handleKeyboardHeightChange
+          );
+          return () => sub.remove();
+        })()
+      );
+
+      subscriptions.push(
+        (() => {
+          const sub = KeyboardEventEmitter.addListener(
+            'keyboardDidShow',
+            handleKeyboardDidShow
+          );
+          return () => sub.remove();
+        })()
+      );
+
+      subscriptions.push(
+        (() => {
+          const sub = KeyboardEventEmitter.addListener(
+            'keyboardDidHide',
+            handleKeyboardDidHide
+          );
+          return () => sub.remove();
+        })()
+      );
+
+      // iOS only events
+      if (Platform.OS === 'ios') {
+        subscriptions.push(
+          (() => {
+            const sub = KeyboardEventEmitter.addListener(
+              'keyboardWillShow',
+              handleKeyboardWillShow
+            );
+            return () => sub.remove();
+          })()
+        );
+
+        subscriptions.push(
+          (() => {
+            const sub = KeyboardEventEmitter.addListener(
+              'keyboardWillHide',
+              handleKeyboardWillHide
+            );
+            return () => sub.remove();
+          })()
+        );
+      }
+    } else {
+      // Fall back to React Native Keyboard API
+      const mapRNKeyboardEvent = (e: any): KeyboardEvent => ({
+        height: e.endCoordinates?.height ?? 0,
+        isVisible: true,
+        duration: e.duration ? e.duration * 1000 : 250,
+        screenHeight: e.endCoordinates?.screenY ?? 0,
+        timestamp: Date.now(),
+        endCoordinates: e.endCoordinates,
+        startCoordinates: e.startCoordinates,
+      });
+
+      const showSub = Keyboard.addListener('keyboardDidShow', (e) =>
+        handleKeyboardDidShow(mapRNKeyboardEvent(e))
+      );
+      const hideSub = Keyboard.addListener('keyboardDidHide', (e) =>
+        handleKeyboardDidHide({
+          height: 0,
+          isVisible: false,
+          timestamp: Date.now(),
+        })
+      );
+
+      subscriptions.push(() => showSub.remove());
+      subscriptions.push(() => hideSub.remove());
+
+      if (Platform.OS === 'ios') {
+        const willShowSub = Keyboard.addListener('keyboardWillShow', (e) =>
+          handleKeyboardWillShow(mapRNKeyboardEvent(e))
+        );
+        const willHideSub = Keyboard.addListener('keyboardWillHide', (e) =>
+          handleKeyboardWillHide({
+            height: 0,
+            isVisible: false,
+            timestamp: Date.now(),
+          })
+        );
+
+        subscriptions.push(() => willShowSub.remove());
+        subscriptions.push(() => willHideSub.remove());
+      }
+    }
+
+    // Cleanup
+    return () => {
+      subscriptions.forEach((unsub) => unsub());
+
+      if (nativeModuleActive.current) {
+        UniversalKeyboardModule.stopListening().catch(() => {});
+        nativeModuleActive.current = false;
+      }
+    };
+  }, [
+    isEnabled,
+    useNativeEvents,
+    handleKeyboardHeightChange,
+    handleKeyboardWillShow,
+    handleKeyboardWillHide,
+    handleKeyboardDidShow,
+    handleKeyboardDidHide,
+  ]);
+
+  return {
+    ...keyboardState,
+    dismissKeyboard,
+  };
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * react-native-universal-keyboard-aware-scrollview
+ *
+ * A universal keyboard-aware ScrollView for React Native that works correctly
+ * in normal screens, modals, and bottom sheets on both Android and iOS.
+ *
+ * @packageDocumentation
+ */
+
+// Native module and event types
+export { UniversalKeyboardModule } from './NativeModule';
+export type {
+  KeyboardEvent,
+  KeyboardEventName,
+  KeyboardCoordinates,
+} from './types';
+
+// Hook
+export { useKeyboard } from './hooks/useKeyboard';
+export type { UseKeyboardOptions, UseKeyboardReturn } from './hooks/useKeyboard';
+
+// Components
+export { KeyboardAwareScrollView } from './components/KeyboardAwareScrollView';
+export type { KeyboardAwareScrollViewProps } from './components/KeyboardAwareScrollView';
+
+// Utilities
+export { KeyboardController } from './utils/KeyboardController';

package/src/types.ts

@@ -0,0 +1,87 @@
+/**
+ * Type definitions for the Universal Keyboard module
+ */
+
+/**
+ * Coordinates describing the keyboard frame
+ */
+export interface KeyboardCoordinates {
+  /** X position of the keyboard on screen */
+  screenX: number;
+  /** Y position of the keyboard on screen */
+  screenY: number;
+  /** Width of the keyboard */
+  width: number;
+  /** Height of the keyboard */
+  height: number;
+}
+
+/**
+ * Event data emitted for keyboard state changes
+ */
+export interface KeyboardEvent {
+  /** Current keyboard height in points/dp */
+  height: number;
+  /** Whether the keyboard is currently visible */
+  isVisible: boolean;
+  /** Animation duration in milliseconds (iOS only) */
+  duration?: number;
+  /** Animation easing curve (iOS only) */
+  easing?: string;
+  /** Screen height in points/dp */
+  screenHeight?: number;
+  /** Screen width in points/dp (iOS only) */
+  screenWidth?: number;
+  /** Safe area bottom inset (iOS only, for notch devices) */
+  safeAreaBottom?: number;
+  /** End coordinates of the keyboard frame (iOS only) */
+  endCoordinates?: KeyboardCoordinates;
+  /** Start coordinates of the keyboard frame (iOS only) */
+  startCoordinates?: KeyboardCoordinates;
+  /** Timestamp of the event */
+  timestamp: number;
+}
+
+/**
+ * Names of keyboard events emitted by the native module
+ */
+export type KeyboardEventName =
+  | 'keyboardDidShow'
+  | 'keyboardDidHide'
+  | 'keyboardHeightChanged'
+  | 'keyboardWillShow'
+  | 'keyboardWillHide';
+
+/**
+ * Native module interface
+ */
+export interface UniversalKeyboardNativeModule {
+  /** Start listening for keyboard events */
+  startListening(): Promise<boolean>;
+  /** Stop listening for keyboard events */
+  stopListening(): Promise<boolean>;
+  /** Get the current keyboard height */
+  getKeyboardHeight(): Promise<number>;
+  /** Check if the keyboard is currently visible */
+  isKeyboardVisible(): Promise<boolean>;
+  /** Dismiss the keyboard */
+  dismissKeyboard(): Promise<boolean>;
+  /** Add listener (required by RN EventEmitter) */
+  addListener(eventName: string): void;
+  /** Remove listeners (required by RN EventEmitter) */
+  removeListeners(count: number): void;
+}
+
+/**
+ * Options for keyboard behavior
+ */
+export interface KeyboardOptions {
+  /** Enable keyboard handling on Android */
+  enableOnAndroid?: boolean;
+  /** Enable keyboard handling on iOS */
+  enableOnIOS?: boolean;
+  /** Extra space to add above the keyboard */
+  extraOffset?: number;
+  /** Behavior when keyboard appears: 'padding', 'position', or 'height' */
+  behavior?: 'padding' | 'position' | 'height';
+}

package/src/utils/KeyboardController.ts

@@ -0,0 +1,112 @@
+import { Keyboard, Platform } from 'react-native';
+import {
+  UniversalKeyboardModule,
+  isNativeModuleAvailable,
+} from '../NativeModule';
+
+/**
+ * KeyboardController - Utility class for programmatic keyboard control
+ *
+ * Provides static methods for dismissing the keyboard and querying keyboard state.
+ * Uses native module when available for more reliable behavior in modals.
+ */
+export class KeyboardController {
+  /**
+   * Dismiss the keyboard programmatically
+   *
+   * Uses native implementation when available for better reliability,
+   * especially in modal contexts.
+   */
+  static async dismiss(): Promise<void> {
+    if (isNativeModuleAvailable()) {
+      try {
+        await UniversalKeyboardModule.dismissKeyboard();
+        return;
+      } catch (error) {
+        // Fall through to RN Keyboard
+      }
+    }
+    Keyboard.dismiss();
+  }
+
+  /**
+   * Get the current keyboard height
+   *
+   * @returns Keyboard height in points/dp, or 0 if keyboard is hidden
+   */
+  static async getHeight(): Promise<number> {
+    if (isNativeModuleAvailable()) {
+      try {
+        return await UniversalKeyboardModule.getKeyboardHeight();
+      } catch (error) {
+        return 0;
+      }
+    }
+    return 0;
+  }
+
+  /**
+   * Check if the keyboard is currently visible
+   *
+   * @returns true if keyboard is visible, false otherwise
+   */
+  static async isVisible(): Promise<boolean> {
+    if (isNativeModuleAvailable()) {
+      try {
+        return await UniversalKeyboardModule.isKeyboardVisible();
+      } catch (error) {
+        return false;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Start listening for keyboard events on the native side
+   *
+   * Call this if you want to use the native event emitter directly.
+   * Usually not needed as useKeyboard hook handles this automatically.
+   */
+  static async startListening(): Promise<boolean> {
+    if (isNativeModuleAvailable()) {
+      try {
+        return await UniversalKeyboardModule.startListening();
+      } catch (error) {
+        return false;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Stop listening for keyboard events on the native side
+   *
+   * Call this to clean up native listeners if you called startListening directly.
+   */
+  static async stopListening(): Promise<boolean> {
+    if (isNativeModuleAvailable()) {
+      try {
+        return await UniversalKeyboardModule.stopListening();
+      } catch (error) {
+        return false;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Check if the current platform is supported
+   */
+  static isSupported(): boolean {
+    return Platform.OS === 'ios' || Platform.OS === 'android';
+  }
+
+  /**
+   * Check if native module is available
+   */
+  static isNativeModuleAvailable(): boolean {
+    return isNativeModuleAvailable();
+  }
+}
+
+export default KeyboardController;

package/src/utils/index.ts

@@ -0,0 +1 @@
+export { KeyboardController } from './KeyboardController';