@minbong/keyboard-inset 0.1.0

package/README.md

@@ -0,0 +1,143 @@
+# @react-native-utils/keyboard-inset
+
+A set of React Native hooks for handling keyboard insets, overlays, and stable cursor behavior across iOS and Android.
+
+This library solves common but tricky issues such as:
+- Incorrect keyboard height on Android
+- Floating toolbars hidden behind the keyboard
+- Cursor jumping on iOS during undo/redo
+- Stable selection handling for TextInput
+
+---
+
+## ✨ Features
+
+- 📐 Accurate keyboard inset calculation (iOS & Android)
+- 🧩 Overlay registration system (toolbars, accessories, etc.)
+- 🔄 Undo / Redo with stable cursor restoration
+- 🍎 iOS cursor offset fixes
+- 🤖 Android keyboard behavior normalization
+- ⚙️ Fully typed (TypeScript)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @react-native-utils/keyboard-inset
+# or
+yarn add @react-native-utils/keyboard-inset
+```
+
+---
+
+## 🚀 Basic Usage
+
+```ts
+import { useKeyboardInset } from '@react-native-utils/keyboard-inset';
+
+const { keyboardInset, keyboardVisible } = useKeyboardInset();
+```
+
+### API
+
+#### `useKeyboardInset()`
+
+```ts
+const {
+  keyboardInset,   // number: bottom inset to apply
+  keyboardVisible, // boolean: whether the keyboard is visible
+  registerOverlay, // (height: number) => () => void
+} = useKeyboardInset();
+```
+
+- `keyboardInset`: Calculated bottom inset that accounts for the keyboard and any registered overlays.
+- `keyboardVisible`: Whether the keyboard is currently visible.
+- `registerOverlay(height)`: Registers an overlay (e.g. toolbar).  
+  Returns a cleanup function that unregisters it on unmount.
+
+```tsx
+<View style={{ position: 'absolute', bottom: keyboardInset }}>
+  ...
+</View>
+```
+
+---
+
+## 🧩 Registering an Overlay (Toolbar, Accessory, etc.)
+
+If your screen has a floating toolbar that should sit above the keyboard:
+
+```ts
+const { registerOverlay } = useKeyboardInset();
+
+useEffect(() => {
+  return registerOverlay(44); // overlay height
+}, []);
+```
+The inset will automatically adjust while the overlay is mounted.
+
+---
+
+## 🔄 Undo / Redo with Stable Cursor
+
+```ts
+import { useUndoRedoWithSelection } from '@react-native-utils/keyboard-inset';
+
+const {
+  currentText,
+  commitHistory,
+  undoStep,
+  redoStep,
+  registerSelection,
+} = useUndoRedoWithSelection({
+  initialValue: '',
+  inputRef,
+});
+```
+
+```tsx
+<TextInput
+  ref={inputRef}
+  value={currentText}
+  onChangeText={commitHistory}
+  onSelectionChange={e =>
+    registerSelection(e.nativeEvent.selection)
+  }
+/>
+```
+### ✅ Cursor behavior
+- Normal typing: cursor is untouched
+- Undo / Redo: cursor is restored accurately
+- iOS mid-text edits: no jumping
+
+---
+
+## ⚠️ iOS Notes
+
+On iOS, `TextInput` selection can be off by one after undo/redo operations.
+This library applies a platform-specific correction **only during history navigation**.
+Normal typing and mid-text edits are never interfered with.
+
+---
+
+## 🧠 Design Philosophy
+
+- Hooks report facts, not assumptions
+- UI components declare their presence
+- Cursor control is applied only when necessary
+
+``Cursor position should only be restored during undo/redo, never during normal typing.``
+
+---
+
+## ❓ Why this library exists
+
+React Native does not provide a reliable, cross-platform way to:
+
+- Measure the real keyboard inset on Android
+- Keep floating toolbars above the keyboard
+- Preserve cursor position during undo/redo on iOS
+
+This package addresses those gaps with a small, focused set of hooks that follow
+React's rules and native platform behaviors.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { useKeyboardInset } from './useKeyboardInset';
+export { useUndoRedoWithSelection } from './useUndoRedoWithSelection';
+export type { Selection } from './useUndoRedoWithSelection';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { useKeyboardInset } from './useKeyboardInset';
+export { useUndoRedoWithSelection } from './useUndoRedoWithSelection';

package/dist/useKeyboardInset.d.ts

@@ -0,0 +1,5 @@
+export declare function useKeyboardInset(): {
+    keyboardVisible: boolean;
+    keyboardInset: number;
+    registerOverlay: (height: number) => () => void;
+};

package/dist/useKeyboardInset.js

@@ -0,0 +1,47 @@
+import { useEffect, useRef, useState, useCallback } from 'react';
+import { Keyboard, Platform } from 'react-native';
+export function useKeyboardInset() {
+    const keyboardHeightRef = useRef(0);
+    const overlayHeightsRef = useRef(new Map());
+    const [visible, setVisible] = useState(false);
+    const [, forceRender] = useState(0);
+    useEffect(() => {
+        const showSub = Keyboard.addListener('keyboardDidShow', e => {
+            keyboardHeightRef.current = e.endCoordinates.height;
+            setVisible(true);
+            forceRender(v => v + 1);
+        });
+        const hideSub = Keyboard.addListener('keyboardDidHide', () => {
+            keyboardHeightRef.current = 0;
+            setVisible(false);
+            forceRender(v => v + 1);
+        });
+        return () => {
+            showSub.remove();
+            hideSub.remove();
+        };
+    }, []);
+    /**
+     * 🔑 Overlay 등록 (Toolbar, Accessory 등)
+     * mount 시 호출, unmount 시 자동 해제
+     */
+    const registerOverlay = useCallback((height) => {
+        const id = Date.now() + Math.random();
+        overlayHeightsRef.current.set(id, height);
+        forceRender(v => v + 1);
+        return () => {
+            overlayHeightsRef.current.delete(id);
+            forceRender(v => v + 1);
+        };
+    }, []);
+    const keyboardHeight = keyboardHeightRef.current;
+    const overlayHeight = Array.from(overlayHeightsRef.current.values()).reduce((sum, h) => sum + h, 0);
+    const keyboardInset = Platform.OS === 'android'
+        ? keyboardHeight + overlayHeight
+        : keyboardHeight;
+    return {
+        keyboardVisible: visible,
+        keyboardInset,
+        registerOverlay,
+    };
+}

package/dist/useUndoRedo.d.ts

@@ -0,0 +1,15 @@
+export type UndoRedoState<T> = {
+    past: T[];
+    present: T;
+    future: T[];
+};
+export declare function useUndoRedo<T>(initialState: T): {
+    state: T;
+    set: (next: T) => void;
+    undo: () => void;
+    redo: () => void;
+    reset: (next: T) => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    history: UndoRedoState<T>;
+};

package/dist/useUndoRedo.js

@@ -0,0 +1,56 @@
+import { useCallback, useState } from 'react';
+export function useUndoRedo(initialState) {
+    const [state, setState] = useState({
+        past: [],
+        present: initialState,
+        future: [],
+    });
+    const set = useCallback((next) => {
+        setState(prev => {
+            if (Object.is(prev.present, next))
+                return prev;
+            return {
+                past: [...prev.past, prev.present],
+                present: next,
+                future: [],
+            };
+        });
+    }, []);
+    const undo = useCallback(() => {
+        setState(prev => {
+            if (!prev.past.length)
+                return prev;
+            const previous = prev.past[prev.past.length - 1];
+            return {
+                past: prev.past.slice(0, -1),
+                present: previous,
+                future: [prev.present, ...prev.future],
+            };
+        });
+    }, []);
+    const redo = useCallback(() => {
+        setState(prev => {
+            if (!prev.future.length)
+                return prev;
+            const next = prev.future[0];
+            return {
+                past: [...prev.past, prev.present],
+                present: next,
+                future: prev.future.slice(1),
+            };
+        });
+    }, []);
+    const reset = useCallback((next) => {
+        setState({ past: [], present: next, future: [] });
+    }, []);
+    return {
+        state: state.present,
+        set,
+        undo,
+        redo,
+        reset,
+        canUndo: state.past.length > 0,
+        canRedo: state.future.length > 0,
+        history: state,
+    };
+}

package/dist/useUndoRedoWithSelection.d.ts

@@ -0,0 +1,17 @@
+export type Selection = {
+    start: number;
+    end: number;
+};
+export declare function useUndoRedoWithSelection({ initialValue, inputRef, }: {
+    initialValue: string;
+    inputRef?: React.RefObject<any>;
+}): {
+    currentText: string;
+    commitHistory: (text: string) => void;
+    undoStep: () => void;
+    redoStep: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    registerSelection: (selection: Selection) => void;
+    resetHistory: (text: string) => void;
+};

package/dist/useUndoRedoWithSelection.js

@@ -0,0 +1,78 @@
+import { useEffect, useRef } from 'react';
+import { Platform } from 'react-native';
+import { useUndoRedo } from './useUndoRedo';
+export function useUndoRedoWithSelection({ initialValue, inputRef, }) {
+    const lastSelectionRef = useRef({
+        start: initialValue.length,
+        end: initialValue.length,
+    });
+    const undoCore = useUndoRedo({
+        text: initialValue,
+        selection: {
+            start: initialValue.length,
+            end: initialValue.length,
+        },
+    });
+    const isHistoryNavigationRef = useRef(false);
+    const undoStep = () => {
+        isHistoryNavigationRef.current = true;
+        undoCore.undo();
+    };
+    const redoStep = () => {
+        isHistoryNavigationRef.current = true;
+        undoCore.redo();
+    };
+    /**
+     * ✅ selection change는 "참고용"
+     * (undo 복원 시 사용)
+     */
+    const registerSelection = (selection) => {
+        lastSelectionRef.current = selection;
+    };
+    /**
+     * ✅ commit 시점에 selection을 "확정"해서 만든다
+     */
+    const commitHistory = (text) => {
+        undoCore.set({
+            text,
+            selection: lastSelectionRef.current,
+        });
+    };
+    /**
+     * ✅ undo / redo 이후 커서 복원
+     */
+    useEffect(() => {
+        if (!isHistoryNavigationRef.current)
+            return;
+        if (!(inputRef === null || inputRef === void 0 ? void 0 : inputRef.current))
+            return;
+        requestAnimationFrame(() => {
+            var _a, _b;
+            let selectionToRestore = undoCore.state.selection;
+            const textLength = undoCore.state.text.length;
+            if (Platform.OS === 'ios' && selectionToRestore.start < textLength) {
+                selectionToRestore = {
+                    start: selectionToRestore.start + 1,
+                    end: selectionToRestore.end + 1,
+                };
+            }
+            (_b = (_a = inputRef.current).setNativeProps) === null || _b === void 0 ? void 0 : _b.call(_a, {
+                selection: selectionToRestore,
+            });
+            isHistoryNavigationRef.current = false;
+        });
+    }, [undoCore.state, inputRef]);
+    return {
+        currentText: undoCore.state.text,
+        commitHistory,
+        undoStep,
+        redoStep,
+        canUndo: undoCore.canUndo,
+        canRedo: undoCore.canRedo,
+        registerSelection,
+        resetHistory: (text) => undoCore.reset({
+            text,
+            selection: { start: text.length, end: text.length },
+        }),
+    };
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name" : "@minbong/keyboard-inset",
+  "version" : "0.1.0",
+  "description" : "React Native hooks for accurate keyboard insets, overlay registration, and stable cursor behavior (iOS & Android).",
+  "main" : "dist/index.js",
+  "types" : "dist/index.d.ts",
+  "exports" : {
+    "." : {
+      "types" : "./dist/index.d.ts",
+      "default" : "./dist/index.js"
+    }
+  },
+  "files" : [
+    "dist"
+  ],
+  "scripts" : {
+    "build" : "tsc",
+    "prepublishOnly" : "npm run build"
+  },
+  "peerDependencies" : {
+    "react" : ">=17",
+    "react-native" : ">=0.68"
+  },
+  "license" : "MIT",
+  "devDependencies" : {
+    "@types/react" : "^18.2.0",
+    "@types/react-native" : "^0.72.8",
+    "typescript" : "^5.9.3"
+  }
+}