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

package/src/components/KeyboardAwareView.tsx

@@ -0,0 +1,172 @@
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react';
+import { Animated, StyleSheet } from 'react-native';
+import type { KeyboardAwareViewProps } from '../types';
+import type { KeyboardAwareViewRef } from '../types';
+import { DEFAULT_KEYBOARD_SPACING } from '../utils/constants';
+import { useKeyboardState } from '../hooks/useKeyboardState';
+import {
+  calculateKeyboardDisplacement,
+  calculateKeyboardOverlap,
+} from '../utils/scrollManager';
+
+/** Adds keyboard spacing to in-flow content and keeps absolute footers visible. */
+export const KeyboardAwareView: React.ForwardRefExoticComponent<
+  KeyboardAwareViewProps & React.RefAttributes<KeyboardAwareViewRef>
+> = forwardRef<KeyboardAwareViewRef, KeyboardAwareViewProps>(
+  function KeyboardAwareViewComponent(
+    {
+      behavior = 'smart',
+      keyboardSpacing = DEFAULT_KEYBOARD_SPACING,
+      enabled = true,
+      style,
+      onLayout,
+      ...props
+    },
+    forwardedRef,
+  ): React.JSX.Element {
+    const keyboard = useKeyboardState();
+    const viewRef = useRef<KeyboardAwareViewRef>(null);
+    useImperativeHandle(forwardedRef, () => viewRef.current!, []);
+    const measurementSequence = useRef(0);
+    const [keyboardOverlap, setKeyboardOverlap] = useState(0);
+    const [keyboardDisplacement, setKeyboardDisplacement] = useState(0);
+    const animatedDisplacement = useRef(new Animated.Value(0)).current;
+    const flattenedStyle = StyleSheet.flatten(style);
+    const isAbsolutelyPositioned = flattenedStyle?.position === 'absolute';
+    const spacing = Number.isFinite(keyboardSpacing)
+      ? Math.max(0, keyboardSpacing)
+      : 0;
+    const basePadding =
+      typeof flattenedStyle?.paddingBottom === 'number'
+        ? flattenedStyle.paddingBottom
+        : 0;
+    const measureOverlap = useCallback(() => {
+      const view = viewRef.current;
+      if (!view?.measureInWindow || !keyboard.isVisible) {
+        return;
+      }
+
+      const sequence = ++measurementSequence.current;
+      view.measureInWindow((_x, y, _width, height) => {
+        if (sequence !== measurementSequence.current || !keyboard.isVisible) {
+          return;
+        }
+        if (!isAbsolutelyPositioned) {
+          setKeyboardOverlap(
+            calculateKeyboardOverlap(
+              { y, height },
+              keyboard.height,
+              keyboard.screenY,
+            ),
+          );
+        }
+        setKeyboardDisplacement(
+          isAbsolutelyPositioned && typeof keyboard.screenY === 'number'
+            ? calculateKeyboardDisplacement(
+                { y, height },
+                keyboard.screenY,
+                spacing,
+              )
+            : 0,
+        );
+      });
+    }, [
+      isAbsolutelyPositioned,
+      keyboard.height,
+      keyboard.isVisible,
+      keyboard.screenY,
+      spacing,
+    ]);
+
+    useEffect(() => {
+      if (!keyboard.isVisible) {
+        measurementSequence.current += 1;
+        setKeyboardOverlap(0);
+        setKeyboardDisplacement(0);
+        return;
+      }
+      const frame = requestAnimationFrame(measureOverlap);
+      return () => cancelAnimationFrame(frame);
+    }, [keyboard.isVisible, keyboard.height, keyboard.screenY, measureOverlap]);
+
+    const shouldAdjust =
+      enabled &&
+      keyboard.isVisible &&
+      behavior !== 'none' &&
+      behavior !== 'resize';
+    useEffect(() => {
+      if (!isAbsolutelyPositioned) {
+        animatedDisplacement.setValue(0);
+        return;
+      }
+      const animation = Animated.timing(animatedDisplacement, {
+        toValue: shouldAdjust ? -keyboardDisplacement : 0,
+        duration: keyboard.animationDuration,
+        useNativeDriver: true,
+      });
+      animation.start();
+      return () => animation.stop();
+    }, [
+      animatedDisplacement,
+      isAbsolutelyPositioned,
+      keyboard.animationDuration,
+      keyboardDisplacement,
+      shouldAdjust,
+    ]);
+
+    const handleLayout = useCallback(
+      (event: Parameters<NonNullable<typeof onLayout>>[0]) => {
+        onLayout?.(event);
+        measureOverlap();
+      },
+      [measureOverlap, onLayout],
+    );
+    const adjustPadding =
+      shouldAdjust &&
+      !isAbsolutelyPositioned &&
+      keyboardOverlap > 0 &&
+      typeof flattenedStyle?.paddingBottom !== 'string';
+    const stickyTransform = isAbsolutelyPositioned
+      ? [
+          ...(Array.isArray(flattenedStyle?.transform)
+            ? flattenedStyle.transform
+            : []),
+          { translateY: animatedDisplacement },
+        ]
+      : undefined;
+
+    return (
+      <Animated.View
+        {...props}
+        ref={viewRef}
+        onLayout={handleLayout}
+        style={
+          adjustPadding
+            ? [
+                style,
+                {
+                  paddingBottom: Math.max(
+                    basePadding,
+                    keyboardOverlap + spacing,
+                  ),
+                },
+              ]
+            : isAbsolutelyPositioned
+            ? [style, { transform: stickyTransform }]
+            : style
+        }
+      />
+    );
+  },
+);
+
+KeyboardAwareView.displayName = 'KeyboardAwareView';
+
+export default KeyboardAwareView;

package/src/components/KeyboardDismissButton.tsx

@@ -0,0 +1,32 @@
+import React from 'react';
+import { Keyboard, Pressable } from 'react-native';
+import type { KeyboardDismissButtonProps } from '../types';
+
+/** A pressable that dismisses the software keyboard by default. */
+export function KeyboardDismissButton({
+  children,
+  onPress,
+  dismissKeyboard = true,
+  accessibilityLabel = 'Dismiss keyboard',
+  ...props
+}: KeyboardDismissButtonProps): React.JSX.Element {
+  const handlePress = () => {
+    onPress?.();
+    if (dismissKeyboard) {
+      Keyboard.dismiss();
+    }
+  };
+
+  return (
+    <Pressable
+      {...props}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityRole="button"
+      onPress={handlePress}
+    >
+      {children}
+    </Pressable>
+  );
+}
+
+export default KeyboardDismissButton;

package/src/components/KeyboardToolbar.tsx

@@ -0,0 +1,200 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  Keyboard,
+  Pressable,
+  StyleSheet,
+  Text,
+  TextInput,
+  View,
+} from 'react-native';
+import type { KeyboardToolbarProps } from '../types';
+import { useKeyboardState } from '../hooks/useKeyboardState';
+
+function findFocusedInputIndex(
+  inputRefs: NonNullable<KeyboardToolbarProps['inputRefs']>,
+): number {
+  return inputRefs.findIndex(ref => ref.current?.isFocused() === true);
+}
+
+function isMountedInputAt(
+  inputRefs: NonNullable<KeyboardToolbarProps['inputRefs']>,
+  index: number,
+): boolean {
+  return (
+    index >= 0 && index < inputRefs.length && inputRefs[index]?.current != null
+  );
+}
+
+function hasMountedInputBefore(
+  inputRefs: NonNullable<KeyboardToolbarProps['inputRefs']>,
+  index: number,
+): boolean {
+  return inputRefs.some(
+    (input, inputIndex) => inputIndex < index && input.current != null,
+  );
+}
+
+function hasMountedInputAfter(
+  inputRefs: NonNullable<KeyboardToolbarProps['inputRefs']>,
+  index: number,
+): boolean {
+  return inputRefs.some(
+    (input, inputIndex) => inputIndex > index && input.current != null,
+  );
+}
+
+/** An optional in-layout toolbar for input navigation and keyboard dismissal. */
+export function KeyboardToolbar({
+  inputRefs = [],
+  focusedInputIndex,
+  onFocusedInputChange,
+  onDone,
+  doneText = 'Done',
+  children,
+  alwaysVisible = false,
+  style,
+  ...props
+}: KeyboardToolbarProps): React.JSX.Element | null {
+  const keyboard = useKeyboardState();
+  const [trackedIndex, setTrackedIndex] = useState(-1);
+  const lastReportedIndex = useRef(-1);
+  const trackFocus = useCallback(() => {
+    const index = findFocusedInputIndex(inputRefs);
+    setTrackedIndex(current => (current === index ? current : index));
+    if (lastReportedIndex.current !== index) {
+      lastReportedIndex.current = index;
+      onFocusedInputChange?.(index);
+    }
+  }, [inputRefs, onFocusedInputChange]);
+
+  useEffect(() => {
+    trackFocus();
+    if (!keyboard.isVisible && !alwaysVisible) {
+      return;
+    }
+
+    const interval = setInterval(trackFocus, 100);
+    return () => clearInterval(interval);
+  }, [alwaysVisible, keyboard.isVisible, trackFocus]);
+
+  if (!alwaysVisible && !keyboard.isVisible) {
+    return null;
+  }
+
+  const actualFocusedIndex = findFocusedInputIndex(inputRefs);
+  const currentIndex =
+    actualFocusedIndex >= 0
+      ? actualFocusedIndex
+      : isMountedInputAt(inputRefs, trackedIndex)
+      ? trackedIndex
+      : isMountedInputAt(inputRefs, focusedInputIndex ?? -1)
+      ? focusedInputIndex!
+      : -1;
+  const canNavigateBackward =
+    currentIndex >= 0 && hasMountedInputBefore(inputRefs, currentIndex);
+  const canNavigateForward =
+    currentIndex >= 0 && hasMountedInputAfter(inputRefs, currentIndex);
+
+  const focusInDirection = (direction: -1 | 1) => {
+    const actualIndex = findFocusedInputIndex(inputRefs);
+    const origin = actualIndex >= 0 ? actualIndex : currentIndex;
+    if (origin < 0) {
+      return;
+    }
+
+    for (
+      let index = origin + direction;
+      index >= 0 && index < inputRefs.length;
+      index += direction
+    ) {
+      const target = inputRefs[index]?.current;
+      if (target) {
+        target.focus();
+        lastReportedIndex.current = index;
+        setTrackedIndex(index);
+        onFocusedInputChange?.(index);
+        return;
+      }
+    }
+  };
+
+  const done = () => {
+    const focusedInput = TextInput.State.currentlyFocusedInput?.();
+    if (focusedInput) {
+      TextInput.State.blurTextInput(focusedInput);
+    }
+    Keyboard.dismiss();
+    onDone?.();
+  };
+
+  return (
+    <View {...props} style={[styles.toolbar, style]}>
+      {children ?? (
+        <>
+          <Pressable
+            accessibilityRole="button"
+            accessibilityLabel="Previous input"
+            disabled={!canNavigateBackward}
+            onPress={() => focusInDirection(-1)}
+            style={styles.action}
+          >
+            <Text style={canNavigateBackward ? styles.label : styles.disabled}>
+              Previous
+            </Text>
+          </Pressable>
+          <Pressable
+            accessibilityRole="button"
+            accessibilityLabel="Next input"
+            disabled={!canNavigateForward}
+            onPress={() => focusInDirection(1)}
+            style={styles.action}
+          >
+            <Text style={canNavigateForward ? styles.label : styles.disabled}>
+              Next
+            </Text>
+          </Pressable>
+          <View style={styles.spacer} />
+          <Pressable
+            accessibilityRole="button"
+            accessibilityLabel="Done"
+            onPress={done}
+            style={styles.action}
+          >
+            <Text style={styles.label}>{doneText}</Text>
+          </Pressable>
+        </>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  toolbar: {
+    alignItems: 'center',
+    backgroundColor: '#f6f7f9',
+    borderTopColor: '#d8dce2',
+    borderTopWidth: StyleSheet.hairlineWidth,
+    flexDirection: 'row',
+    minHeight: 48,
+    paddingHorizontal: 12,
+  },
+  action: {
+    minHeight: 44,
+    justifyContent: 'center',
+    paddingHorizontal: 10,
+  },
+  label: {
+    color: '#155eef',
+    fontSize: 15,
+    fontWeight: '600',
+  },
+  disabled: {
+    color: '#98a2b3',
+    fontSize: 15,
+  },
+  spacer: {
+    flex: 1,
+  },
+});
+
+export default KeyboardToolbar;

package/src/components/index.ts

@@ -0,0 +1,4 @@
+export { KeyboardAwareScrollView } from './KeyboardAwareScrollView';
+export { KeyboardAwareView } from './KeyboardAwareView';
+export { KeyboardToolbar } from './KeyboardToolbar';
+export { KeyboardDismissButton } from './KeyboardDismissButton';

package/src/context/KeyboardContext.tsx

@@ -0,0 +1,35 @@
+import React, { createContext, useContext, useEffect, useRef } from 'react';
+import { useKeyboardState } from '../hooks/useKeyboardState';
+import type { KeyboardProviderProps } from '../types';
+
+const DebugContext = createContext(false);
+
+/** Optional provider for development diagnostics; keyboard subscriptions are shared globally. */
+export function KeyboardProvider({
+  children,
+  debug = false,
+}: KeyboardProviderProps): React.JSX.Element {
+  const keyboard = useKeyboardState();
+  const previous = useRef(keyboard);
+
+  useEffect(() => {
+    if (
+      debug &&
+      __DEV__ &&
+      (previous.current.isVisible !== keyboard.isVisible ||
+        previous.current.height !== keyboard.height)
+    ) {
+      console.debug('[keyboard-toolkit]', keyboard);
+    }
+    previous.current = keyboard;
+  }, [debug, keyboard]);
+
+  return (
+    <DebugContext.Provider value={debug}>{children}</DebugContext.Provider>
+  );
+}
+
+/** Read whether development diagnostics are enabled on the nearest provider. */
+export function useKeyboardDebug(): boolean {
+  return useContext(DebugContext);
+}

package/src/context/index.ts

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

package/src/hooks/index.ts

@@ -0,0 +1,4 @@
+export { useKeyboard } from './useKeyboard';
+export { useKeyboardState } from './useKeyboardState';
+export { useKeyboardAnimation } from './useKeyboardAnimation';
+export { useFocusedInput } from './useFocusedInput';

package/src/hooks/useFocusedInput.ts

@@ -0,0 +1,52 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { FocusedInputLayout } from '../types';
+import { getFocusedInput, measureFocusedInput } from '../utils/focusManager';
+import { useKeyboardState } from './useKeyboardState';
+
+/** Measure the focused TextInput when the keyboard opens; call `refresh` after layout changes. */
+export function useFocusedInput(): {
+  focusedInput: FocusedInputLayout | null;
+  refresh: () => Promise<FocusedInputLayout | null>;
+} {
+  const keyboard = useKeyboardState();
+  const [focusedInput, setFocusedInput] = useState<FocusedInputLayout | null>(
+    null,
+  );
+  const measureSequence = useRef(0);
+
+  const refresh = useCallback(async () => {
+    const sequence = ++measureSequence.current;
+    const layout = await measureFocusedInput(getFocusedInput());
+    if (sequence === measureSequence.current) {
+      setFocusedInput(current => {
+        if (
+          current?.x === layout?.x &&
+          current?.y === layout?.y &&
+          current?.width === layout?.width &&
+          current?.height === layout?.height
+        ) {
+          return current;
+        }
+        return layout;
+      });
+    }
+    return layout;
+  }, []);
+
+  useEffect(() => {
+    if (!keyboard.isVisible) {
+      measureSequence.current += 1;
+      setFocusedInput(null);
+      return;
+    }
+
+    refresh();
+    const interval = setInterval(refresh, 120);
+    return () => {
+      measureSequence.current += 1;
+      clearInterval(interval);
+    };
+  }, [keyboard.isVisible, keyboard.height, refresh]);
+
+  return { focusedInput, refresh };
+}

package/src/hooks/useKeyboard.ts

@@ -0,0 +1 @@
+export { useKeyboardState as useKeyboard } from './useKeyboardState';

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';