react-native-keyboard-toolkit 0.0.0-stage → 1.0.0

package/src/hooks/useKeyboardAnimation.ts

@@ -0,0 +1,50 @@
+import { useEffect, useRef, useState } from 'react';
+import { AccessibilityInfo, Animated } from 'react-native';
+import { useKeyboardState } from './useKeyboardState';
+
+/** Provides an animated 0-to-1 visibility value and the native event duration. */
+export function useKeyboardAnimation(): {
+  progress: Animated.Value;
+  animationDuration: number;
+} {
+  const keyboard = useKeyboardState();
+  const progressRef = useRef<Animated.Value | null>(null);
+  if (!progressRef.current) {
+    progressRef.current = new Animated.Value(keyboard.progress);
+  }
+  const progress = progressRef.current;
+  const [reduceMotion, setReduceMotion] = useState(false);
+
+  useEffect(() => {
+    let active = true;
+    AccessibilityInfo.isReduceMotionEnabled()
+      .then(enabled => {
+        if (active) {
+          setReduceMotion(enabled);
+        }
+      })
+      .catch(() => {
+        // Keep animations enabled when the platform preference cannot be read.
+      });
+    const subscription = AccessibilityInfo.addEventListener(
+      'reduceMotionChanged',
+      setReduceMotion,
+    );
+    return () => {
+      active = false;
+      subscription.remove();
+    };
+  }, []);
+
+  useEffect(() => {
+    const animation = Animated.timing(progress, {
+      toValue: keyboard.progress,
+      duration: reduceMotion ? 0 : keyboard.animationDuration,
+      useNativeDriver: true,
+    });
+    animation.start();
+    return () => animation.stop();
+  }, [keyboard.animationDuration, keyboard.progress, progress, reduceMotion]);
+
+  return { progress, animationDuration: keyboard.animationDuration };
+}

package/src/hooks/useKeyboardState.ts

@@ -0,0 +1,14 @@
+import { useSyncExternalStore } from 'react';
+import {
+  getKeyboardState,
+  subscribeKeyboardState,
+} from '../utils/keyboardEvents';
+
+/** Subscribe to the shared, normalized keyboard state. A provider is optional. */
+export function useKeyboardState() {
+  return useSyncExternalStore(
+    subscribeKeyboardState,
+    getKeyboardState,
+    getKeyboardState,
+  );
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+export {
+  KeyboardAwareScrollView,
+  KeyboardAwareView,
+  KeyboardDismissButton,
+  KeyboardToolbar,
+} from './components';
+export { KeyboardProvider } from './context';
+export {
+  useFocusedInput,
+  useKeyboard,
+  useKeyboardAnimation,
+  useKeyboardState,
+} from './hooks';
+export {
+  calculateScrollOffset,
+  calculateKeyboardOverlap,
+  focusInput,
+  getFocusedInput,
+  isAndroid,
+  isIOS,
+  measureFocusedInput,
+} from './utils';
+export type {
+  FocusedInputLayout,
+  KeyboardAwareScrollViewProps,
+  KeyboardAwareScrollViewRef,
+  KeyboardAwareViewProps,
+  KeyboardAwareViewRef,
+  KeyboardBehavior,
+  KeyboardDismissButtonProps,
+  KeyboardProviderProps,
+  KeyboardState,
+  KeyboardToolbarProps,
+  TextInputRef,
+} from './types';

package/src/types/index.ts

@@ -0,0 +1,101 @@
+import type {
+  ScrollView,
+  ScrollViewProps,
+  StyleProp,
+  TextInput,
+  View,
+  ViewProps,
+  ViewStyle,
+} from 'react-native';
+import type {
+  ComponentPropsWithRef,
+  ElementRef,
+  ReactNode,
+  RefObject,
+} from 'react';
+
+type RefTarget<T> = T extends RefObject<infer Value>
+  ? NonNullable<Value>
+  : never;
+
+export type TextInputRef = RefTarget<
+  NonNullable<ComponentPropsWithRef<typeof TextInput>['ref']>
+>;
+
+export type KeyboardAwareScrollViewRef = ElementRef<typeof ScrollView>;
+export type KeyboardAwareViewRef = ElementRef<typeof View>;
+
+/** Layout strategies supported by the keyboard-aware components. */
+export type KeyboardBehavior =
+  | 'smart'
+  | 'scroll'
+  | 'resize'
+  | 'padding'
+  | 'none';
+
+/** A normalized snapshot of the most recent on-screen keyboard event. */
+export interface KeyboardState {
+  isVisible: boolean;
+  height: number;
+  progress: 0 | 1;
+  animationDuration: number;
+  screenY?: number;
+}
+
+export interface KeyboardAwareScrollViewProps extends ScrollViewProps {
+  /** Defaults to `smart`, which scrolls only when the focused field is covered. */
+  behavior?: KeyboardBehavior;
+  /** Space to leave between the focused field and keyboard, in points. */
+  keyboardSpacing?: number;
+  /** Disable keyboard-driven padding and focus scrolling. */
+  enabled?: boolean;
+}
+
+export interface KeyboardAwareViewProps extends ViewProps {
+  /** Defaults to `smart`. `resize` relies on the platform window resize behavior. */
+  behavior?: KeyboardBehavior;
+  /** Extra space between the view content and the keyboard, in points. */
+  keyboardSpacing?: number;
+  /** Disable keyboard-driven layout changes. */
+  enabled?: boolean;
+}
+
+export interface KeyboardProviderProps {
+  children: ReactNode;
+  /** Log keyboard state changes in development builds. */
+  debug?: boolean;
+}
+
+export interface KeyboardToolbarProps extends ViewProps {
+  /** Refs to the form inputs the toolbar should navigate between. */
+  inputRefs?: readonly RefObject<TextInputRef | null>[];
+  /** @deprecated Focus is detected automatically from the provided input refs. */
+  focusedInputIndex?: number;
+  /** Called when the focused input in `inputRefs` changes. */
+  onFocusedInputChange?: (index: number) => void;
+  /** Called after the Done action dismisses the keyboard. */
+  onDone?: () => void;
+  /** Label shown by the built-in Done button. */
+  doneText?: string;
+  /** Replaces the built-in previous/next/done controls. */
+  children?: ReactNode;
+  /** Render the toolbar while the keyboard is hidden. Defaults to false. */
+  alwaysVisible?: boolean;
+}
+
+export interface KeyboardDismissButtonProps extends ViewProps {
+  children: ReactNode;
+  /** Custom press handler. The keyboard is also dismissed unless disabled. */
+  onPress?: () => void;
+  /** Defaults to true. */
+  dismissKeyboard?: boolean;
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+export interface FocusedInputLayout {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}

package/src/utils/constants.ts

@@ -0,0 +1,2 @@
+export const DEFAULT_KEYBOARD_SPACING = 16;
+export const DEFAULT_ANIMATION_DURATION = 250;

package/src/utils/focusManager.ts

@@ -0,0 +1,40 @@
+import { TextInput } from 'react-native';
+import type { RefObject } from 'react';
+import type { FocusedInputLayout, TextInputRef } from '../types';
+
+type Measurable = Pick<TextInputRef, 'measureInWindow'>;
+
+/** Returns the currently focused native TextInput when React Native exposes it. */
+export function getFocusedInput(): Measurable | null {
+  const input = TextInput.State.currentlyFocusedInput?.();
+  if (input) {
+    return input;
+  }
+
+  return null;
+}
+
+/** Measure the focused TextInput in window coordinates. */
+export function measureFocusedInput(
+  input: Measurable | null = getFocusedInput(),
+): Promise<FocusedInputLayout | null> {
+  if (!input?.measureInWindow) {
+    return Promise.resolve(null);
+  }
+
+  return new Promise(resolve => {
+    input.measureInWindow?.((x, y, width, height) => {
+      resolve({ x, y, width, height });
+    });
+  });
+}
+
+/** Request focus on a TextInput ref and return whether a native input was available. */
+export function focusInput(input: RefObject<TextInputRef | null>): boolean {
+  const node = input.current;
+  if (!node) {
+    return false;
+  }
+  node.focus();
+  return true;
+}

package/src/utils/index.ts

@@ -0,0 +1,10 @@
+export {
+  calculateKeyboardOverlap,
+  calculateScrollOffset,
+} from './scrollManager';
+export {
+  focusInput,
+  getFocusedInput,
+  measureFocusedInput,
+} from './focusManager';
+export { isAndroid, isIOS } from './platform';

package/src/utils/keyboardEvents.ts

@@ -0,0 +1,110 @@
+import {
+  Keyboard,
+  type KeyboardEvent,
+  type EmitterSubscription,
+} from 'react-native';
+import { DEFAULT_ANIMATION_DURATION } from './constants';
+import { getKeyboardEventNames, isIOS } from './platform';
+import type { KeyboardState } from '../types';
+
+const initialState: KeyboardState = {
+  isVisible: false,
+  height: 0,
+  progress: 0,
+  animationDuration: 0,
+};
+
+let state = initialState;
+let listeners: EmitterSubscription[] = [];
+const subscribers = new Set<() => void>();
+
+function update(event: KeyboardEvent, visible: boolean): void {
+  const coordinates = event.endCoordinates;
+  state = {
+    isVisible: visible,
+    height: visible ? Math.max(0, coordinates?.height ?? 0) : 0,
+    progress: visible ? 1 : 0,
+    animationDuration: Math.max(
+      0,
+      event.duration ?? DEFAULT_ANIMATION_DURATION,
+    ),
+    ...(visible && typeof coordinates?.screenY === 'number'
+      ? { screenY: coordinates.screenY }
+      : {}),
+  };
+  subscribers.forEach(subscriber => subscriber());
+}
+
+function syncCurrentKeyboardState(): void {
+  const metrics =
+    typeof Keyboard.metrics === 'function' ? Keyboard.metrics() : undefined;
+  const isVisible =
+    typeof Keyboard.isVisible === 'function'
+      ? Keyboard.isVisible()
+      : metrics != null;
+  if (!isVisible || !metrics) {
+    return;
+  }
+
+  state = {
+    isVisible: true,
+    height: metrics.height,
+    progress: 1,
+    animationDuration: 0,
+    screenY: metrics.screenY,
+  };
+  subscribers.forEach(subscriber => subscriber());
+}
+
+function startListening(): void {
+  const names = getKeyboardEventNames();
+  if (isIOS && names.frameChange) {
+    listeners = [
+      Keyboard.addListener(names.frameChange, event =>
+        update(event, event.endCoordinates.height > 0),
+      ),
+    ];
+    syncCurrentKeyboardState();
+    return;
+  }
+
+  const showSubscription = Keyboard.addListener(names.show, event =>
+    update(event, true),
+  );
+  const hideSubscription = Keyboard.addListener(names.hide, event =>
+    update(event, false),
+  );
+  listeners = [showSubscription, hideSubscription];
+  syncCurrentKeyboardState();
+}
+
+function stopListening(): void {
+  listeners.forEach(subscription => subscription.remove());
+  listeners = [];
+}
+
+/** Subscribe to the shared keyboard event stream. */
+export function subscribeKeyboardState(subscriber: () => void): () => void {
+  subscribers.add(subscriber);
+  if (subscribers.size === 1) {
+    startListening();
+  }
+  return () => {
+    subscribers.delete(subscriber);
+    if (subscribers.size === 0) {
+      stopListening();
+    }
+  };
+}
+
+/** Return the stable current snapshot used by `useSyncExternalStore`. */
+export function getKeyboardState(): KeyboardState {
+  return state;
+}
+
+/** Reset the shared state and event listeners; intended for tests. */
+export function resetKeyboardStateForTests(): void {
+  stopListening();
+  subscribers.clear();
+  state = initialState;
+}

package/src/utils/platform.ts

@@ -0,0 +1,23 @@
+import { Platform } from 'react-native';
+import type { KeyboardEventName } from 'react-native';
+
+/** True when running on iOS. */
+export const isIOS = Platform.OS === 'ios';
+
+/** True when running on Android. */
+export const isAndroid = Platform.OS === 'android';
+
+/** Selects the native keyboard event names for the current platform. */
+export function getKeyboardEventNames(): {
+  show: KeyboardEventName;
+  hide: KeyboardEventName;
+  frameChange?: KeyboardEventName;
+} {
+  return isIOS
+    ? {
+        show: 'keyboardWillShow',
+        hide: 'keyboardWillHide',
+        frameChange: 'keyboardWillChangeFrame',
+      }
+    : { show: 'keyboardDidShow', hide: 'keyboardDidHide' };
+}

package/src/utils/scrollManager.ts

@@ -0,0 +1,59 @@
+export interface ScrollViewport {
+  y: number;
+  height: number;
+}
+
+export interface ScrollInput {
+  y: number;
+  height: number;
+}
+
+export interface ScrollCalculation {
+  offset: number;
+  delta: number;
+}
+
+/** Return the part of the measured view actually covered by the keyboard. */
+export function calculateKeyboardOverlap(
+  viewport: ScrollViewport,
+  keyboardHeight: number,
+  keyboardTop?: number,
+): number {
+  const viewportBottom = viewport.y + viewport.height;
+  const obscuredTop =
+    typeof keyboardTop === 'number'
+      ? Math.max(viewport.y, Math.min(viewportBottom, keyboardTop))
+      : Math.max(viewport.y, viewportBottom - Math.max(0, keyboardHeight));
+
+  return Math.max(0, viewportBottom - obscuredTop);
+}
+
+/**
+ * Calculate the smallest scroll adjustment needed to bring an input into the
+ * visible viewport. `keyboardTop` avoids double-counting Android adjustResize.
+ */
+export function calculateScrollOffset(
+  input: ScrollInput,
+  viewport: ScrollViewport,
+  keyboardHeight: number,
+  spacing: number,
+  currentOffset: number,
+  keyboardTop?: number,
+): ScrollCalculation {
+  const viewportBottom = viewport.y + viewport.height;
+  const unobscuredBottom =
+    viewportBottom -
+    calculateKeyboardOverlap(viewport, keyboardHeight, keyboardTop) -
+    spacing;
+  const unobscuredTop = viewport.y + spacing;
+  const inputBottom = input.y + input.height;
+
+  let delta = 0;
+  if (inputBottom > unobscuredBottom) {
+    delta = inputBottom - unobscuredBottom;
+  } else if (input.y < unobscuredTop) {
+    delta = input.y - unobscuredTop;
+  }
+
+  return { delta, offset: Math.max(0, currentOffset + delta) };
+}