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

package/src/components/KeyboardAwareScrollView.tsx

@@ -0,0 +1,240 @@
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react';
+import { ScrollView, StyleSheet, type LayoutChangeEvent } from 'react-native';
+import type { KeyboardAwareScrollViewProps } from '../types';
+import type { KeyboardAwareScrollViewRef } from '../types';
+import { getFocusedInput, measureFocusedInput } from '../utils/focusManager';
+import {
+  calculateKeyboardOverlap,
+  calculateScrollOffset,
+} from '../utils/scrollManager';
+import { useKeyboardDebug } from '../context/KeyboardContext';
+import { useKeyboardState } from '../hooks/useKeyboardState';
+import { DEFAULT_KEYBOARD_SPACING } from '../utils/constants';
+import { isIOS } from '../utils/platform';
+
+/** A ScrollView that adds keyboard space and scrolls a covered focused input into view. */
+export const KeyboardAwareScrollView: React.ForwardRefExoticComponent<
+  KeyboardAwareScrollViewProps & React.RefAttributes<KeyboardAwareScrollViewRef>
+> = forwardRef<KeyboardAwareScrollViewRef, KeyboardAwareScrollViewProps>(
+  function KeyboardAwareScrollViewComponent(
+    {
+      behavior = 'smart',
+      keyboardSpacing = DEFAULT_KEYBOARD_SPACING,
+      enabled = true,
+      contentContainerStyle,
+      onScroll,
+      onScrollBeginDrag,
+      onContentSizeChange,
+      onLayout,
+      onFocusCapture,
+      scrollEventThrottle = 16,
+      ...props
+    },
+    forwardedRef,
+  ): React.JSX.Element {
+    const keyboard = useKeyboardState();
+    const debug = useKeyboardDebug();
+    const scrollRef = useRef<KeyboardAwareScrollViewRef>(null);
+    useImperativeHandle(forwardedRef, () => scrollRef.current!, []);
+    const scrollOffset = useRef(0);
+    const lastScrollTarget = useRef<number | null>(null);
+    const measurementSequence = useRef(0);
+    const [keyboardOverlap, setKeyboardOverlap] = useState(0);
+    const spacing = Math.max(0, keyboardSpacing);
+
+    const scrollFocusedInput = useCallback(async () => {
+      const sequence = ++measurementSequence.current;
+      if (!enabled || !keyboard.isVisible || behavior === 'resize') {
+        return;
+      }
+
+      const scrollView = scrollRef.current;
+      const input = getFocusedInput();
+      if (!scrollView?.measureInWindow) {
+        return;
+      }
+
+      const viewport = await new Promise<{ y: number; height: number }>(
+        resolve => {
+          scrollView.measureInWindow((_x, y, _width, height) =>
+            resolve({ y, height }),
+          );
+        },
+      );
+
+      if (sequence !== measurementSequence.current || !keyboard.isVisible) {
+        return;
+      }
+
+      const overlap = calculateKeyboardOverlap(
+        viewport,
+        keyboard.height,
+        keyboard.screenY,
+      );
+      if (Math.abs(overlap - keyboardOverlap) > 1) {
+        setKeyboardOverlap(overlap);
+        return;
+      }
+      if (
+        !input?.measureInWindow ||
+        behavior === 'none' ||
+        behavior === 'padding'
+      ) {
+        return;
+      }
+
+      const inputLayout = await measureFocusedInput(input);
+      if (sequence !== measurementSequence.current || !inputLayout) {
+        return;
+      }
+
+      const calculation = calculateScrollOffset(
+        { y: inputLayout.y, height: inputLayout.height },
+        viewport,
+        keyboard.height,
+        spacing,
+        scrollOffset.current,
+        keyboard.screenY,
+      );
+
+      if (debug && __DEV__) {
+        console.debug('[keyboard-toolkit] scroll calculation', calculation);
+      }
+      if (
+        Math.abs(calculation.delta) > 1 &&
+        (lastScrollTarget.current === null ||
+          Math.abs(lastScrollTarget.current - calculation.offset) > 1)
+      ) {
+        lastScrollTarget.current = calculation.offset;
+        scrollView.scrollTo({ y: calculation.offset, animated: true });
+      }
+    }, [
+      behavior,
+      debug,
+      enabled,
+      keyboard.height,
+      keyboard.isVisible,
+      keyboard.screenY,
+      keyboardOverlap,
+      spacing,
+    ]);
+
+    useEffect(() => {
+      if (!keyboard.isVisible) {
+        lastScrollTarget.current = null;
+        measurementSequence.current += 1;
+        setKeyboardOverlap(0);
+        return;
+      }
+      const frame = requestAnimationFrame(() => {
+        scrollFocusedInput();
+      });
+      return () => cancelAnimationFrame(frame);
+    }, [keyboard.height, keyboard.isVisible, scrollFocusedInput]);
+
+    const handleScroll = useCallback(
+      (event: Parameters<NonNullable<typeof onScroll>>[0]) => {
+        scrollOffset.current = event.nativeEvent.contentOffset.y;
+        if (
+          lastScrollTarget.current !== null &&
+          Math.abs(scrollOffset.current - lastScrollTarget.current) <= 1
+        ) {
+          lastScrollTarget.current = null;
+        }
+        onScroll?.(event);
+      },
+      [onScroll],
+    );
+
+    const handleScrollBeginDrag = useCallback(
+      (event: Parameters<NonNullable<typeof onScrollBeginDrag>>[0]) => {
+        lastScrollTarget.current = null;
+        onScrollBeginDrag?.(event);
+      },
+      [onScrollBeginDrag],
+    );
+
+    const handleContentSizeChange = useCallback(
+      (width: number, height: number) => {
+        onContentSizeChange?.(width, height);
+        if (keyboard.isVisible) {
+          requestAnimationFrame(() => scrollFocusedInput());
+        }
+      },
+      [keyboard.isVisible, onContentSizeChange, scrollFocusedInput],
+    );
+
+    const handleLayout = useCallback(
+      (event: LayoutChangeEvent) => {
+        onLayout?.(event);
+        if (keyboard.isVisible) {
+          requestAnimationFrame(() => scrollFocusedInput());
+        }
+      },
+      [keyboard.isVisible, onLayout, scrollFocusedInput],
+    );
+
+    const handleFocusCapture = useCallback(
+      (event: Parameters<NonNullable<typeof onFocusCapture>>[0]) => {
+        onFocusCapture?.(event);
+        if (keyboard.isVisible) {
+          requestAnimationFrame(() => scrollFocusedInput());
+        }
+      },
+      [keyboard.isVisible, onFocusCapture, scrollFocusedInput],
+    );
+
+    const flattenedContentStyle = StyleSheet.flatten(contentContainerStyle);
+    const existingBottomPadding =
+      typeof flattenedContentStyle?.paddingBottom === 'number'
+        ? flattenedContentStyle.paddingBottom
+        : 0;
+    const shouldPad =
+      enabled &&
+      keyboard.isVisible &&
+      behavior !== 'none' &&
+      behavior !== 'resize' &&
+      keyboardOverlap > 0;
+    const adjustedContentStyle =
+      shouldPad && typeof flattenedContentStyle?.paddingBottom !== 'string'
+        ? [
+            contentContainerStyle,
+            {
+              paddingBottom: Math.max(
+                existingBottomPadding,
+                keyboardOverlap + spacing,
+              ),
+            },
+          ]
+        : contentContainerStyle;
+
+    return (
+      <ScrollView
+        {...props}
+        automaticallyAdjustKeyboardInsets={
+          props.automaticallyAdjustKeyboardInsets ??
+          (behavior === 'resize' && isIOS)
+        }
+        ref={scrollRef}
+        contentContainerStyle={adjustedContentStyle}
+        onContentSizeChange={handleContentSizeChange}
+        onLayout={handleLayout}
+        onFocusCapture={handleFocusCapture}
+        onScroll={handleScroll}
+        onScrollBeginDrag={handleScrollBeginDrag}
+        scrollEventThrottle={scrollEventThrottle}
+      />
+    );
+  },
+);
+
+KeyboardAwareScrollView.displayName = 'KeyboardAwareScrollView';
+
+export default KeyboardAwareScrollView;

package/src/components/KeyboardAwareView.tsx

@@ -0,0 +1,112 @@
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react';
+import { StyleSheet, View } 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 { calculateKeyboardOverlap } from '../utils/scrollManager';
+
+/** A lightweight view that adds bottom space while the keyboard is 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 flattenedStyle = StyleSheet.flatten(style);
+    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;
+        }
+        setKeyboardOverlap(
+          calculateKeyboardOverlap(
+            { y, height },
+            keyboard.height,
+            keyboard.screenY,
+          ),
+        );
+      });
+    }, [keyboard.height, keyboard.isVisible, keyboard.screenY]);
+
+    useEffect(() => {
+      if (!keyboard.isVisible) {
+        measurementSequence.current += 1;
+        setKeyboardOverlap(0);
+        return;
+      }
+      const frame = requestAnimationFrame(measureOverlap);
+      return () => cancelAnimationFrame(frame);
+    }, [keyboard.isVisible, keyboard.height, keyboard.screenY, measureOverlap]);
+
+    const handleLayout = useCallback(
+      (event: Parameters<NonNullable<typeof onLayout>>[0]) => {
+        onLayout?.(event);
+        measureOverlap();
+      },
+      [measureOverlap, onLayout],
+    );
+    const adjust =
+      enabled &&
+      keyboard.isVisible &&
+      behavior !== 'none' &&
+      behavior !== 'resize' &&
+      keyboardOverlap > 0 &&
+      typeof flattenedStyle?.paddingBottom !== 'string';
+
+    return (
+      <View
+        {...props}
+        ref={viewRef}
+        onLayout={handleLayout}
+        style={
+          adjust
+            ? [
+                style,
+                {
+                  paddingBottom: Math.max(
+                    basePadding,
+                    keyboardOverlap + Math.max(0, keyboardSpacing),
+                  ),
+                },
+              ]
+            : 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';