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

package/dist/types/index.d.ts

@@ -0,0 +1,69 @@
+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;
+}
+export {};

package/dist/types/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/constants.d.ts

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

package/dist/utils/constants.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ANIMATION_DURATION = exports.DEFAULT_KEYBOARD_SPACING = void 0;
+exports.DEFAULT_KEYBOARD_SPACING = 16;
+exports.DEFAULT_ANIMATION_DURATION = 250;

package/dist/utils/focusManager.d.ts

@@ -0,0 +1,10 @@
+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 declare function getFocusedInput(): Measurable | null;
+/** Measure the focused TextInput in window coordinates. */
+export declare function measureFocusedInput(input?: Measurable | null): Promise<FocusedInputLayout | null>;
+/** Request focus on a TextInput ref and return whether a native input was available. */
+export declare function focusInput(input: RefObject<TextInputRef | null>): boolean;
+export {};

package/dist/utils/focusManager.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFocusedInput = getFocusedInput;
+exports.measureFocusedInput = measureFocusedInput;
+exports.focusInput = focusInput;
+const react_native_1 = require("react-native");
+/** Returns the currently focused native TextInput when React Native exposes it. */
+function getFocusedInput() {
+    const input = react_native_1.TextInput.State.currentlyFocusedInput?.();
+    if (input) {
+        return input;
+    }
+    return null;
+}
+/** Measure the focused TextInput in window coordinates. */
+function measureFocusedInput(input = getFocusedInput()) {
+    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. */
+function focusInput(input) {
+    const node = input.current;
+    if (!node) {
+        return false;
+    }
+    node.focus();
+    return true;
+}

package/dist/utils/index.d.ts

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

package/dist/utils/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isIOS = exports.isAndroid = exports.measureFocusedInput = exports.getFocusedInput = exports.focusInput = exports.calculateScrollOffset = exports.calculateKeyboardOverlap = void 0;
+var scrollManager_1 = require("./scrollManager");
+Object.defineProperty(exports, "calculateKeyboardOverlap", { enumerable: true, get: function () { return scrollManager_1.calculateKeyboardOverlap; } });
+Object.defineProperty(exports, "calculateScrollOffset", { enumerable: true, get: function () { return scrollManager_1.calculateScrollOffset; } });
+var focusManager_1 = require("./focusManager");
+Object.defineProperty(exports, "focusInput", { enumerable: true, get: function () { return focusManager_1.focusInput; } });
+Object.defineProperty(exports, "getFocusedInput", { enumerable: true, get: function () { return focusManager_1.getFocusedInput; } });
+Object.defineProperty(exports, "measureFocusedInput", { enumerable: true, get: function () { return focusManager_1.measureFocusedInput; } });
+var platform_1 = require("./platform");
+Object.defineProperty(exports, "isAndroid", { enumerable: true, get: function () { return platform_1.isAndroid; } });
+Object.defineProperty(exports, "isIOS", { enumerable: true, get: function () { return platform_1.isIOS; } });

package/dist/utils/keyboardEvents.d.ts

@@ -0,0 +1,7 @@
+import type { KeyboardState } from '../types';
+/** Subscribe to the shared keyboard event stream. */
+export declare function subscribeKeyboardState(subscriber: () => void): () => void;
+/** Return the stable current snapshot used by `useSyncExternalStore`. */
+export declare function getKeyboardState(): KeyboardState;
+/** Reset the shared state and event listeners; intended for tests. */
+export declare function resetKeyboardStateForTests(): void;

package/dist/utils/keyboardEvents.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subscribeKeyboardState = subscribeKeyboardState;
+exports.getKeyboardState = getKeyboardState;
+exports.resetKeyboardStateForTests = resetKeyboardStateForTests;
+const react_native_1 = require("react-native");
+const constants_1 = require("./constants");
+const platform_1 = require("./platform");
+const initialState = {
+    isVisible: false,
+    height: 0,
+    progress: 0,
+    animationDuration: 0,
+};
+let state = initialState;
+let listeners = [];
+const subscribers = new Set();
+function update(event, visible) {
+    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 ?? constants_1.DEFAULT_ANIMATION_DURATION),
+        ...(visible && typeof coordinates?.screenY === 'number'
+            ? { screenY: coordinates.screenY }
+            : {}),
+    };
+    subscribers.forEach(subscriber => subscriber());
+}
+function syncCurrentKeyboardState() {
+    const metrics = typeof react_native_1.Keyboard.metrics === 'function' ? react_native_1.Keyboard.metrics() : undefined;
+    const isVisible = typeof react_native_1.Keyboard.isVisible === 'function'
+        ? react_native_1.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() {
+    const names = (0, platform_1.getKeyboardEventNames)();
+    if (platform_1.isIOS && names.frameChange) {
+        listeners = [
+            react_native_1.Keyboard.addListener(names.frameChange, event => update(event, event.endCoordinates.height > 0)),
+        ];
+        syncCurrentKeyboardState();
+        return;
+    }
+    const showSubscription = react_native_1.Keyboard.addListener(names.show, event => update(event, true));
+    const hideSubscription = react_native_1.Keyboard.addListener(names.hide, event => update(event, false));
+    listeners = [showSubscription, hideSubscription];
+    syncCurrentKeyboardState();
+}
+function stopListening() {
+    listeners.forEach(subscription => subscription.remove());
+    listeners = [];
+}
+/** Subscribe to the shared keyboard event stream. */
+function subscribeKeyboardState(subscriber) {
+    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`. */
+function getKeyboardState() {
+    return state;
+}
+/** Reset the shared state and event listeners; intended for tests. */
+function resetKeyboardStateForTests() {
+    stopListening();
+    subscribers.clear();
+    state = initialState;
+}

package/dist/utils/platform.d.ts

@@ -0,0 +1,11 @@
+import type { KeyboardEventName } from 'react-native';
+/** True when running on iOS. */
+export declare const isIOS: boolean;
+/** True when running on Android. */
+export declare const isAndroid: boolean;
+/** Selects the native keyboard event names for the current platform. */
+export declare function getKeyboardEventNames(): {
+    show: KeyboardEventName;
+    hide: KeyboardEventName;
+    frameChange?: KeyboardEventName;
+};

package/dist/utils/platform.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAndroid = exports.isIOS = void 0;
+exports.getKeyboardEventNames = getKeyboardEventNames;
+const react_native_1 = require("react-native");
+/** True when running on iOS. */
+exports.isIOS = react_native_1.Platform.OS === 'ios';
+/** True when running on Android. */
+exports.isAndroid = react_native_1.Platform.OS === 'android';
+/** Selects the native keyboard event names for the current platform. */
+function getKeyboardEventNames() {
+    return exports.isIOS
+        ? {
+            show: 'keyboardWillShow',
+            hide: 'keyboardWillHide',
+            frameChange: 'keyboardWillChangeFrame',
+        }
+        : { show: 'keyboardDidShow', hide: 'keyboardDidHide' };
+}

package/dist/utils/scrollManager.d.ts

@@ -0,0 +1,19 @@
+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 declare function calculateKeyboardOverlap(viewport: ScrollViewport, keyboardHeight: number, keyboardTop?: number): number;
+/**
+ * Calculate the smallest scroll adjustment needed to bring an input into the
+ * visible viewport. `keyboardTop` avoids double-counting Android adjustResize.
+ */
+export declare function calculateScrollOffset(input: ScrollInput, viewport: ScrollViewport, keyboardHeight: number, spacing: number, currentOffset: number, keyboardTop?: number): ScrollCalculation;

package/dist/utils/scrollManager.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateKeyboardOverlap = calculateKeyboardOverlap;
+exports.calculateScrollOffset = calculateScrollOffset;
+/** Return the part of the measured view actually covered by the keyboard. */
+function calculateKeyboardOverlap(viewport, keyboardHeight, keyboardTop) {
+    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.
+ */
+function calculateScrollOffset(input, viewport, keyboardHeight, spacing, currentOffset, keyboardTop) {
+    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) };
+}

package/docs/android.md

@@ -0,0 +1,26 @@
+# Android testing and setup
+
+The library listens to `keyboardDidShow` / `keyboardDidHide`, measures native
+input and scroll-view frames, and reads the reported keyboard screen coordinate
+when available. It does not edit `MainActivity`, `MainApplication`, or the
+manifest.
+
+For common form behavior, configure the activity to use `adjustResize`. The
+repository app already uses this setting. The components intersect the measured
+viewport with the keyboard's reported top frame; if `adjustResize` has already
+ended the viewport at that frame, the measured overlap is zero and no second
+keyboard-height inset is added. OEM keyboards and edge-to-edge configurations
+can still report coordinates relative to different window origins.
+
+## Device checklist
+
+- Test Android 10+ devices/emulators and the app's minimum supported OS.
+- Try both gesture and three-button navigation.
+- Test `adjustResize` and, if the app supports it, `adjustPan`.
+- Test status/navigation bars, edge-to-edge, and any translucent system bars.
+- Test multiline inputs, modal screens, nested scroll views, and input focus
+  during navigation transitions.
+- Try at least one hardware keyboard and one alternate software keyboard.
+
+This project has not been validated on physical Android devices. Do not treat
+these notes as device compatibility claims.

package/docs/api.md

@@ -0,0 +1,75 @@
+# API reference
+
+## `KeyboardAwareScrollView`
+
+Extends React Native `ScrollViewProps`.
+
+- `behavior?: 'smart' | 'scroll' | 'resize' | 'padding' | 'none'` (default
+  `'smart'`): smart and scroll behaviors minimally scroll a covered focused
+  input; padding extends the scroll range without focus scrolling; resize uses
+  automatic keyboard insets on iOS and relies on window resizing on Android;
+  none disables keyboard adjustment.
+- `keyboardSpacing?: number` (default `16`): spacing in points.
+- `enabled?: boolean` (default `true`): disable keyboard adjustments.
+
+The component measures its viewport and the focused native input. It adds
+scrollable bottom space based on measured viewport/keyboard-frame overlap,
+avoiding blindly adding the full keyboard height when the OS has resized the
+window. Existing numeric bottom padding is preserved. Its ref points to the
+underlying React Native `ScrollView`.
+
+## `KeyboardAwareView`
+
+Extends `ViewProps`. Supports `behavior`, `keyboardSpacing`, and `enabled`.
+Smart, scroll, and padding add bottom padding for the measured overlap. Resize
+and none do not add padding. This view does not scroll to reveal a hidden child.
+Its ref points to the underlying React Native `View`.
+
+## `KeyboardProvider`
+
+`<KeyboardProvider debug={false}>children</KeyboardProvider>`. It is optional;
+set `debug` to log state changes in development.
+
+## `KeyboardToolbar`
+
+Extends `ViewProps` and accepts:
+
+- `inputRefs?: readonly RefObject<TextInputRef | null>[]`: refs ordered for
+  Previous/Next navigation. The currently focused ref is detected
+  automatically.
+- `onFocusedInputChange?: (index: number) => void`: called when a supplied ref
+  becomes or ceases to be focused; `-1` means no supplied ref is focused.
+- `onDone?: () => void`, `doneText?: string`, and `alwaysVisible?: boolean`.
+- `children?: ReactNode`: replaces the default controls.
+
+Previous and Next skip null/unmounted refs and are disabled when no mounted
+input exists in that direction. Done blurs the focused native input when
+available, calls `Keyboard.dismiss()`, then invokes `onDone`. The deprecated
+`focusedInputIndex` prop remains supported for compatibility; it is not needed
+for automatic focus tracking.
+
+## `KeyboardDismissButton`
+
+Accepts `children`, `onPress`, `dismissKeyboard` (default `true`),
+`accessibilityLabel`, and React Native `ViewProps`. The optional callback runs
+before keyboard dismissal.
+
+## Hooks
+
+- `useKeyboardState()` and its alias `useKeyboard()` return a stable
+  `KeyboardState`: `{ isVisible, height, progress, animationDuration, screenY? }`.
+- `useKeyboardAnimation()` returns `{ progress: Animated.Value,
+animationDuration }`.
+- `useFocusedInput()` returns `{ focusedInput, refresh }`; the layout is
+  window-relative or `null` when the focused input cannot be measured.
+
+The package entry point also exports `calculateKeyboardOverlap`,
+`calculateScrollOffset`, `focusInput`, `getFocusedInput`, `isAndroid`, `isIOS`,
+`measureFocusedInput`, and the `TextInputRef` type used by toolbar refs. The
+`KeyboardAwareScrollViewRef` and `KeyboardAwareViewRef` types describe the
+corresponding component refs.
+
+`calculateKeyboardOverlap(viewport, keyboardHeight, keyboardTop?)` returns the
+measured overlap. `calculateScrollOffset(input, viewport, keyboardHeight,
+spacing, currentOffset, keyboardTop?)` returns `{ offset, delta }`. The
+coordinate values must use the same window-coordinate system.

package/docs/assets/demo-preview.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="540" viewBox="0 0 960 540" role="img" aria-labelledby="title description">
+  <title id="title">Keyboard Shepherd illustrative demo preview</title>
+  <desc id="description">An illustration of a keyboard-aware profile form above a software keyboard.</desc>
+  <rect width="960" height="540" fill="#f4f6fb"/>
+  <text x="54" y="58" fill="#101828" font-family="Arial, sans-serif" font-size="26" font-weight="700">Keyboard Shepherd</text>
+  <text x="54" y="86" fill="#667085" font-family="Arial, sans-serif" font-size="15">Illustrative form layout — keyboard-aware scrolling</text>
+  <rect x="250" y="110" width="460" height="290" rx="18" fill="#ffffff" stroke="#d0d5dd"/>
+  <text x="282" y="151" fill="#101828" font-family="Arial, sans-serif" font-size="21" font-weight="700">Create your profile</text>
+  <text x="282" y="181" fill="#475467" font-family="Arial, sans-serif" font-size="13">Email</text>
+  <rect x="282" y="190" width="396" height="42" rx="8" fill="#ffffff" stroke="#98a2b3"/>
+  <text x="296" y="216" fill="#667085" font-family="Arial, sans-serif" font-size="14">name@example.com</text>
+  <text x="282" y="258" fill="#475467" font-family="Arial, sans-serif" font-size="13">Description</text>
+  <rect x="282" y="267" width="396" height="62" rx="8" fill="#ffffff" stroke="#98a2b3"/>
+  <text x="296" y="293" fill="#667085" font-family="Arial, sans-serif" font-size="14">Input remains visible while typing</text>
+  <rect x="282" y="345" width="396" height="38" rx="8" fill="#155eef"/>
+  <text x="480" y="370" fill="#ffffff" font-family="Arial, sans-serif" font-size="14" font-weight="700" text-anchor="middle">Submit form</text>
+  <rect x="0" y="420" width="960" height="120" fill="#e4e7ec"/>
+  <rect x="24" y="434" width="912" height="30" rx="7" fill="#ffffff"/>
+  <text x="480" y="454" fill="#475467" font-family="Arial, sans-serif" font-size="13" text-anchor="middle">Keyboard toolbar: Previous                     Next                         Done</text>
+  <g fill="#ffffff">
+    <rect x="38" y="475" width="84" height="25" rx="5"/><rect x="132" y="475" width="84" height="25" rx="5"/><rect x="226" y="475" width="84" height="25" rx="5"/><rect x="320" y="475" width="84" height="25" rx="5"/><rect x="414" y="475" width="84" height="25" rx="5"/><rect x="508" y="475" width="84" height="25" rx="5"/><rect x="602" y="475" width="84" height="25" rx="5"/><rect x="696" y="475" width="84" height="25" rx="5"/><rect x="790" y="475" width="84" height="25" rx="5"/>
+    <rect x="82" y="507" width="84" height="25" rx="5"/><rect x="176" y="507" width="84" height="25" rx="5"/><rect x="270" y="507" width="84" height="25" rx="5"/><rect x="364" y="507" width="84" height="25" rx="5"/><rect x="458" y="507" width="84" height="25" rx="5"/><rect x="552" y="507" width="84" height="25" rx="5"/><rect x="646" y="507" width="84" height="25" rx="5"/><rect x="740" y="507" width="84" height="25" rx="5"/>
+  </g>
+</svg>

package/docs/installation.md

@@ -0,0 +1,22 @@
+# Installation
+
+```sh
+npm install react-native-keyboard-toolkit
+```
+
+React and React Native are peer dependencies. The package uses only React Native
+JavaScript APIs, so it does not require native linking, a Pod, a config plugin,
+or a custom Expo development client.
+
+## React Native CLI
+
+1. Install the package in the app.
+2. Use `KeyboardAwareScrollView` around the form content.
+3. On Android, keep the activity's `windowSoftInputMode` at `adjustResize` for
+   the conventional resizable-window behavior.
+
+## Expo
+
+Use the package from an Expo app as you would any JavaScript-only dependency.
+The keyboard APIs are included in Expo Go. The development demo lives in the
+repository's React Native host app; it is not a generated Expo project.

package/docs/ios.md

@@ -0,0 +1,22 @@
+# iOS testing
+
+The library consumes iOS keyboard frame-change events and uses
+`measureInWindow` for the focused field and its scroll viewport. The intersection
+of those measured window coordinates with the keyboard frame determines the
+temporary scroll range, so safe-area-constrained viewports do not blindly add
+the full keyboard height. The library does not set safe-area, navigation, or
+modal presentation configuration.
+
+## Device checklist
+
+- Test iPhone and iPad layouts with safe areas and the home indicator.
+- Verify navigation headers and bottom tab bars are outside the measured form
+  region or included in its layout.
+- Test multiline inputs, interactive keyboard dismissal, and modal screens.
+- On iPad, test floating and split keyboards where available.
+- Test hardware keyboard attachment and focus transitions.
+- Check input behavior during navigation animations.
+
+Floating/split keyboards and transition-time measurements may not describe one
+contiguous obscured area. Automated unit tests cannot validate native keyboard
+geometry; test on actual simulators/devices before release.

package/docs/troubleshooting.md

@@ -0,0 +1,36 @@
+# Troubleshooting
+
+## The focused field does not scroll
+
+- Confirm the input is a native React Native `TextInput`, not an unmeasurable
+  third-party wrapper.
+- Ensure the focused input belongs to the scroll view and has completed layout.
+- Check that `enabled` is true and the behavior is `smart` or `scroll`.
+- If a custom input wrapper delays focus, call `refresh()` from
+  `useFocusedInput` after its layout settles.
+
+## Android content is moved twice
+
+Use `adjustResize` as the standard window mode and avoid adding a second
+keyboard-height spacer around the same content. The scroll view uses the event
+screen coordinate where available, but unusual edge-to-edge or OEM keyboard
+configurations may need a custom layout.
+
+## Keyboard height is zero or unexpected
+
+Hardware keyboards may not open a software keyboard. Floating and split
+keyboards can occupy only part of the screen and do not have a useful full-width
+height. Keyboard-reported heights can differ with navigation bars and OS
+versions.
+
+## Nested views add too much space
+
+Use one keyboard-padding component per layout region. A nested aware view and
+scroll view both respond to the same keyboard state; disable one with
+`behavior="resize"` or `enabled={false}` when only one should adjust.
+
+## The keyboard hides a modal field
+
+Place the scroll view inside the modal content and verify the modal's measured
+window frame. Presentation styles and window insets vary; test on the target
+platform rather than assuming the main screen's coordinates apply to a modal.

package/package.json

@@ -1,6 +1,92 @@
 {
   "name": "react-native-keyboard-toolkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Keyboard-aware ScrollView, keyboard avoiding view, input focus navigation, and keyboard state hooks for React Native on iOS and Android.",
+  "author": "Denish Dabhi <dabhidenish57@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/DenishDabhi/react-native-keyboard-toolkit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DenishDabhi/react-native-keyboard-toolkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DenishDabhi/react-native-keyboard-toolkit/issues"
+  },
+  "main": "dist/index.js",
+  "react-native": "src/index.ts",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "keywords": [
+    "react-native",
+    "keyboard",
+    "keyboard-aware",
+    "keyboard-management",
+    "keyboard-avoiding",
+    "scrollview",
+    "textinput",
+    "expo",
+    "ios",
+    "android",
+    "typescript",
+    "keyboard-dismiss",
+    "keyboard-handling"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "android": "react-native run-android",
+    "ios": "react-native run-ios",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint src tests demo App.tsx --ext .ts,.tsx",
+    "format:check": "prettier --check src tests demo App.tsx package.json README.md CHANGELOG.md docs",
+    "start": "react-native start",
+    "test": "jest --runInBand",
+    "validate": "npm run typecheck && npm run lint && npm run format:check && npm test && npm run build && npm pack --dry-run",
+    "prepublishOnly": "npm run validate"
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0",
+    "react-native": ">=0.71.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.25.2",
+    "@babel/preset-env": "^7.25.3",
+    "@babel/runtime": "^7.25.0",
+    "@react-native-community/cli": "20.2.0",
+    "@react-native-community/cli-platform-android": "20.2.0",
+    "@react-native-community/cli-platform-ios": "20.2.0",
+    "@react-native/babel-preset": "0.88.1",
+    "@react-native/eslint-config": "0.88.1",
+    "@react-native/jest-preset": "0.88.1",
+    "@react-native/metro-config": "0.88.1",
+    "@react-native/typescript-config": "0.88.1",
+    "@types/jest": "^29.5.13",
+    "@types/react": "^19.2.0",
+    "@types/react-test-renderer": "^19.1.0",
+    "eslint": "^8.19.0",
+    "jest": "^29.6.3",
+    "prettier": "2.8.8",
+    "react": "19.3.0",
+    "react-native": "0.88.1",
+    "react-native-safe-area-context": "^5.5.2",
+    "react-test-renderer": "19.3.0",
+    "typescript": "^6.0.3"
+  }
+}