@mrmeg/expo-ui 0.11.0 → 0.12.1

package/CHANGELOG.md

@@ -3,6 +3,42 @@
 All notable changes to `@mrmeg/expo-ui` are documented here. This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.12.1]
+
+### Fixed
+
+- **`BottomSheet` now dismisses the keyboard when tapping outside a focused
+  field on Android.** The native sheet hosts its content in a separate window
+  (via `@expo/ui`'s `RNHostView`), outside the app's `KeyboardProvider` — so the
+  app-wide tap-away never reached sheet content, and `useKeyboardState()` /
+  `KeyboardController.dismiss()` are blind to that window. iOS papered over this
+  (SwiftUI resigns first-responder on outside taps for free); Compose did not,
+  leaving a focused field stuck open. `BottomSheet.Content` now mounts a
+  transparent dismiss overlay while a field is focused, detecting focus via the
+  window-independent `keyboardFocusRegistry` and resigning the field through its
+  own native `blur()` ref. The registry gained `subscribeKeyboardFocus`,
+  `hasKeyboardFocusedInput`, and `dismissKeyboardFocusedInput`, and `TextInput`
+  now registers a `blur` handle on focus.
+
+## [0.12.0]
+
+### Added
+
+- **`KeyboardAvoidingView` is now a public package component.** Native uses
+  `react-native-keyboard-controller` with `automaticOffset` enabled by default,
+  while web renders a plain `View`.
+- **`UIProvider` now owns app-wide native keyboard avoidance by default.** Apps
+  that mount `KeyboardProvider` above `UIProvider` get root-level keyboard
+  avoiding behavior without adding per-screen `KeyboardAvoidingView` wrappers.
+  Pass `keyboardAvoiding={false}` to opt out, or `keyboardAvoidingProps` to tune
+  the root wrapper. Web skips the root keyboard wrapper unless explicitly
+  enabled.
+
+### Fixed
+
+- **`DismissKeyboard` no longer nests keyboard-avoiding wrappers when the root
+  provider already owns keyboard avoidance.**
+
 ## [0.11.0]
 
 ### Added

package/LLM_USAGE.md

@@ -177,6 +177,7 @@ Use this table before creating a new app-local primitive.
 | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | One-off disclosure | Local animated height wrappers | Advanced settings, hidden helper text |
 | `Dialog`, `AlertDialog` | Modal decisions and custom modal content | Custom modal overlays | Confirm delete, edit profile, invite user |
 | `DismissKeyboard` | Tap-away keyboard dismissal | Screen-level keyboard handling | Forms, search screens, sign-in screens |
+| `KeyboardAvoidingView` | Native keyboard-aware layout root | Repeated app-local keyboard wrappers | Screen roots, composer footers, form-heavy subtrees |
 | `Drawer` | Side panels and drawer navigation | Custom sliding panels | Filter drawer, app navigation drawer, inspector panel |
 | `DropdownMenu` | Menus and command lists | Homemade popover menus | Row actions, account menu, sort menu |
 | `EmptyState` | No-data or recoverable error regions | One-off empty placeholders | Empty inbox, no search results, failed list load |

package/README.md

@@ -222,6 +222,7 @@ All components are exported from `@mrmeg/expo-ui/components`; direct imports suc
 | `ErrorBoundary` | React render error fallback | Unhandled screen crashes | Route-level fallback, feature boundary, recoverable widget crashes |
 | `Icon` | Feather or custom icons with theme tokens | Raw vector icons with hardcoded colors | Button accessories, empty-state icons, menu icons, status glyphs |
 | `InputOTP` | Verification code entry | Multiple manually managed text inputs | Email codes, SMS codes, MFA, invite codes |
+| `KeyboardAvoidingView` | Native keyboard-aware layout root | Repeated app-local keyboard wrappers | Screen roots, composer footers, form-heavy subtrees |
 | `Label` | Accessible form labels | Plain styled text labels | Required labels, disabled labels, field group labels |
 | `MaxWidthContainer` | Centered responsive width | Per-screen max-width wrappers | Web pages, tablet layouts, settings forms, auth panels |
 | `Notification` | Global toast surface | Screen-local toast state | Saved/error/sync notifications, action toasts, loading toast, bottom-position alerts |
@@ -272,7 +273,7 @@ Use `Button.preset`, not `variant`. `default` is the neutral primary action, `se
 
 Use `StyledText` or its aliases instead of raw `Text` whenever the text is part of app UI. Use `TextInput` for labeled fields because it already owns label, helper text, error text, clear buttons, password visibility, numeric filtering, and left/right elements.
 
-Mount `UIProvider` once near the root before using `Dialog`, `AlertDialog`, `BottomSheet`, `Drawer`, `DropdownMenu`, `Popover`, `SelectContent`, `Tooltip`, or package notifications. On native, `BottomSheet.Content` listens to React Native keyboard events when `avoidKeyboard` is enabled; it defaults to `true` and can be disabled per sheet. Trigger transient feedback with `notify`.
+Mount `UIProvider` once near the root before using `Dialog`, `AlertDialog`, `BottomSheet`, `Drawer`, `DropdownMenu`, `Popover`, `SelectContent`, `Tooltip`, or package notifications. On native, `UIProvider` also wraps app content in the package keyboard-avoiding root by default, so ordinary screens and fixed footers stay above the soft keyboard without repeated app-local wrappers; pass `keyboardAvoiding={false}` to opt out, or use `KeyboardAvoidingView` directly for a subtree with custom behavior. Web skips the root keyboard wrapper unless `keyboardAvoiding` is explicitly enabled. `BottomSheet.Content` listens to React Native keyboard events when `avoidKeyboard` is enabled; it defaults to `true` and can be disabled per sheet. Trigger transient feedback with `notify`.
 
 Use `Skeleton` components for loading content with stable dimensions, `EmptyState` for no-data/recoverable errors, `Alert` for blocking confirm/alert dialogs, and `Notification` for transient global feedback.
 

package/dist/components/BottomSheet.js

@@ -1,12 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import React, { createContext, use, useCallback, useEffect, useReducer, useRef } from "react";
-import { View, Pressable, ScrollView, Platform, useWindowDimensions, } from "react-native";
+import React, { createContext, use, useCallback, useEffect, useMemo, useReducer, useRef, useSyncExternalStore } from "react";
+import { View, Pressable, StyleSheet, ScrollView, Platform, useWindowDimensions, } from "react-native";
 import { BottomSheet as NativeBottomSheet } from "@expo/ui/community/bottom-sheet";
+import { KeyboardController } from "react-native-keyboard-controller";
 import { useSafeAreaInsets, initialWindowMetrics } from "react-native-safe-area-context";
 import { useTheme } from "../hooks/useTheme.js";
 import { spacing } from "../constants/spacing.js";
 import { TextColorContext, TextClassContext } from "./StyledText.context";
 import { Icon } from "./Icon.js";
+import { dismissKeyboardFocusedInput, hasKeyboardFocusedInput, subscribeKeyboardFocus, } from "./keyboardFocusRegistry.js";
+const DEFAULT_SNAP_POINTS = ["50%"];
 function clampSnapIndex(index, maxSnapIndex) {
     return Math.min(Math.max(index, 0), maxSnapIndex);
 }
@@ -22,25 +25,42 @@ function createInitialRootState(defaultOpen, maxSnapIndex) {
 }
 function bottomSheetRootReducer(state, action) {
     switch (action.type) {
-        case "setInternalOpen":
+        case "setInternalOpen": {
+            const snapIndex = action.open ? state.snapIndex : action.maxSnapIndex;
+            const snapDirection = action.open ? state.snapDirection : -1;
+            if (state.internalOpen === action.open &&
+                state.snapIndex === snapIndex &&
+                state.snapDirection === snapDirection) {
+                return state;
+            }
             return {
                 ...state,
                 internalOpen: action.open,
-                snapIndex: action.open ? state.snapIndex : action.maxSnapIndex,
-                snapDirection: action.open ? state.snapDirection : -1,
+                snapIndex,
+                snapDirection,
             };
+        }
         case "setScrollable":
+            if (state.scrollable === action.scrollable)
+                return state;
             return { ...state, scrollable: action.scrollable };
         case "setHasHeader":
+            if (state.hasHeader === action.present)
+                return state;
             return { ...state, hasHeader: action.present };
         case "setHasFooter":
+            if (state.hasFooter === action.present)
+                return state;
             return { ...state, hasFooter: action.present };
         case "setSnapIndex": {
             const snapIndex = clampSnapIndex(action.index, action.maxSnapIndex);
+            const snapDirection = snapIndex === 0 ? 1 : snapIndex === action.maxSnapIndex ? -1 : state.snapDirection;
+            if (state.snapIndex === snapIndex && state.snapDirection === snapDirection)
+                return state;
             return {
                 ...state,
                 snapIndex,
-                snapDirection: snapIndex === 0 ? 1 : snapIndex === action.maxSnapIndex ? -1 : state.snapDirection,
+                snapDirection,
             };
         }
         case "cycleSnapPoint": {
@@ -140,9 +160,51 @@ function SheetCloseButton({ style }) {
         ], children: _jsx(Icon, { name: "x", size: 22, color: "text" }) }));
 }
 // ============================================================================
+// Keyboard dismiss overlay — tap-away dismissal inside the sheet
+// ============================================================================
+/**
+ * Tap-away keyboard dismissal for sheet content.
+ *
+ * The native sheet (SwiftUI `.sheet()` / Material `ModalBottomSheet`) hosts its
+ * RN children in a separate native window via @expo/ui's `RNHostView`, OUTSIDE
+ * the app's `KeyboardProvider` / `KeyboardDismissBoundary`. Two consequences,
+ * both worked around here:
+ *
+ *  1. Detection: `react-native-keyboard-controller`'s `useKeyboardState` watches
+ *     the main window and does NOT see a keyboard raised inside the sheet's
+ *     window (the same isolation that makes `useSafeAreaInsets()` read zero in
+ *     here). So presence is read from the `keyboardFocusRegistry` instead, which
+ *     is fed by @expo/ui's own native focus events and is window-independent.
+ *  2. Dispatch: RN's JS responder chain (onStartShouldSetResponder*) is NOT
+ *     dispatched across the `RNHostView` boundary on Android — only `Pressable`
+ *     hit-testing (native `measure()`) works inside the host. So this is a
+ *     transparent `Pressable` mounted ONLY while a field is focused, mirroring
+ *     the app's `DismissKeyboardOverlay`. The tap blurs the focused field via
+ *     its own native ref (`dismissKeyboardFocusedInput`), which resigns the
+ *     responder regardless of window; `KeyboardController.dismiss()` is a
+ *     best-effort fallback for the (rare) case with no registered blur handle.
+ *
+ * iOS doesn't strictly need this (SwiftUI resigns first-responder on outside
+ * taps for free), but the same path is harmless and keeps behavior identical.
+ */
+function SheetKeyboardDismissOverlay() {
+    const hasFocus = useSyncExternalStore(subscribeKeyboardFocus, hasKeyboardFocusedInput, () => false);
+    if (Platform.OS === "web" || !hasFocus)
+        return null;
+    return (_jsx(Pressable, { style: [StyleSheet.absoluteFill, styles.keyboardDismissOverlay], onPressIn: () => {
+            if (!dismissKeyboardFocusedInput())
+                KeyboardController.dismiss();
+        }, accessibilityLabel: "Dismiss keyboard", accessibilityRole: "button" }));
+}
+const styles = StyleSheet.create({
+    keyboardDismissOverlay: {
+        zIndex: 999,
+    },
+});
+// ============================================================================
 // Root
 // ============================================================================
-function BottomSheetRoot({ open: controlledOpen, onOpenChange: controlledOnOpenChange, defaultOpen = false, snapPoints = ["50%"], closeOnBackdropPress = true, children, }) {
+function BottomSheetRoot({ open: controlledOpen, onOpenChange: controlledOnOpenChange, defaultOpen = false, snapPoints = DEFAULT_SNAP_POINTS, closeOnBackdropPress = true, children, }) {
     const maxSnapIndex = Math.max(snapPoints.length - 1, 0);
     const [state, dispatch] = useReducer(bottomSheetRootReducer, undefined, () => createInitialRootState(defaultOpen, maxSnapIndex));
     const isControlled = controlledOpen !== undefined;
@@ -167,7 +229,16 @@ function BottomSheetRoot({ open: controlledOpen, onOpenChange: controlledOnOpenC
         }
     }, [controlledOnOpenChange, isControlled, maxSnapIndex]);
     const toggle = useCallback(() => onOpenChange(!open), [onOpenChange, open]);
-    const contextValue = {
+    const setScrollable = useCallback((scrollable) => {
+        dispatch({ type: "setScrollable", scrollable });
+    }, []);
+    const setHasHeader = useCallback((present) => {
+        dispatch({ type: "setHasHeader", present });
+    }, []);
+    const setHasFooter = useCallback((present) => {
+        dispatch({ type: "setHasFooter", present });
+    }, []);
+    const contextValue = useMemo(() => ({
         open,
         onOpenChange,
         toggle,
@@ -177,12 +248,27 @@ function BottomSheetRoot({ open: controlledOpen, onOpenChange: controlledOnOpenC
         cycleSnapPoint,
         closeOnBackdropPress,
         scrollable: state.scrollable,
-        setScrollable: (scrollable) => dispatch({ type: "setScrollable", scrollable }),
+        setScrollable,
         hasHeader: state.hasHeader,
-        setHasHeader: (present) => dispatch({ type: "setHasHeader", present }),
+        setHasHeader,
         hasFooter: state.hasFooter,
-        setHasFooter: (present) => dispatch({ type: "setHasFooter", present }),
-    };
+        setHasFooter,
+    }), [
+        open,
+        onOpenChange,
+        toggle,
+        snapPoints,
+        snapIndex,
+        setSnapIndex,
+        cycleSnapPoint,
+        closeOnBackdropPress,
+        state.scrollable,
+        setScrollable,
+        state.hasHeader,
+        setHasHeader,
+        state.hasFooter,
+        setHasFooter,
+    ]);
     return (_jsx(BottomSheetContext.Provider, { value: contextValue, children: children }));
 }
 // ============================================================================
@@ -259,7 +345,7 @@ swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDra
                             backgroundColor: theme.colors.card,
                         },
                         styleOverride,
-                    ], children: [children, showFloatingClose && (_jsx(SheetCloseButton, { style: {
+                    ], children: [children, _jsx(SheetKeyboardDismissOverlay, {}), showFloatingClose && (_jsx(SheetCloseButton, { style: {
                                 // The sheet card sits below the status bar, so no top inset
                                 // is needed — just clear the sheet's own top edge / handle.
                                 position: "absolute",

package/dist/components/DismissKeyboard.d.ts

@@ -11,5 +11,5 @@ type Props = {
 /**
  * @returns Wrapper for a view that dismisses the keyboard when tapped outside of a text input
  */
-export declare const DismissKeyboard: ({ children, style, avoidKeyboard, scrollable }: Props) => React.JSX.Element;
+export declare const DismissKeyboard: (props: Props) => React.JSX.Element;
 export {};

package/dist/components/DismissKeyboard.js

@@ -1,9 +1,11 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Pressable, StyleSheet, Platform, KeyboardAvoidingView, ScrollView, View, } from "react-native";
-import { KeyboardController, useKeyboardState } from "react-native-keyboard-controller";
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from "react";
+import { Platform, ScrollView, View, } from "react-native";
+import { KeyboardController, useKeyboardContext, useKeyboardState, } from "react-native-keyboard-controller";
+import { KeyboardAvoidingView, useKeyboardAvoidance } from "./KeyboardAvoidingView.js";
+import { isTouchInsideKeyboardFocusedInput } from "./keyboardFocusRegistry.js";
 /**
- * Full-screen tap-catcher that dismisses the keyboard, mounted ONLY while the
- * keyboard is visible.
+ * Native tap-away keyboard dismissal.
  *
  * Why window-level dismissal: the native `@expo/ui` TextInput is a SwiftUI /
  * Compose field that never registers with React Native's `TextInputState`, so
@@ -11,28 +13,46 @@ import { KeyboardController, useKeyboardState } from "react-native-keyboard-cont
  * `KeyboardController.dismiss()` resigns the focused responder at the IME level,
  * which works for both native and RN fields.
  *
- * Why only-while-visible: an always-mounted catcher would intercept the very tap
- * that focuses a field and close the keyboard before it opens, and would fight
- * bottom sheets / modals. Rendering it solely while the keyboard is up means
- * nothing intercepts taps when no field is focused; once one is, a tap anywhere
- * off the field dismisses.
+ * Why responder capture: a full-screen overlay also catches taps on the focused
+ * input, which breaks double-tap text selection. Capture lets the tap continue
+ * to children while still dismissing when the touch starts outside the focused
+ * input bounds.
  */
-function KeyboardDismissOverlay() {
+function useDismissKeyboardOnOutsideTouch() {
     const isVisible = useKeyboardState((state) => state.isVisible);
-    if (!isVisible)
-        return null;
-    return (_jsx(Pressable, { style: StyleSheet.absoluteFill, onPress: () => KeyboardController.dismiss(), accessibilityLabel: "Dismiss keyboard", accessibilityRole: "button" }));
+    const { layout: focusedInput } = useKeyboardContext();
+    return React.useCallback((event) => {
+        if (Platform.OS === "web" || !isVisible) {
+            return false;
+        }
+        if (isTouchInsideKeyboardFocusedInput(event, focusedInput.value?.layout)) {
+            return false;
+        }
+        KeyboardController.dismiss();
+        return false;
+    }, [focusedInput, isVisible]);
 }
 /**
  * @returns Wrapper for a view that dismisses the keyboard when tapped outside of a text input
  */
-export const DismissKeyboard = ({ children, style, avoidKeyboard = true, scrollable = true }) => {
+function DismissKeyboardLayout({ children, style, avoidKeyboard = true, scrollable = true, dismissOnTouchStart, }) {
+    const hasKeyboardAvoidance = useKeyboardAvoidance();
     const content = scrollable ? (_jsx(ScrollView, { style: { flex: 1 }, contentContainerStyle: { flexGrow: 1, justifyContent: "center" }, keyboardShouldPersistTaps: "handled", showsVerticalScrollIndicator: false, children: children })) : (children);
-    // Web has no software keyboard, so the tap-catcher is native-only. The overlay
-    // is never created on web, keeping `useKeyboardState` off that platform.
-    const overlay = Platform.OS !== "web" ? _jsx(KeyboardDismissOverlay, {}) : null;
-    if (!avoidKeyboard) {
-        return (_jsxs(View, { style: { flex: 1 }, children: [content, overlay] }));
+    if (!avoidKeyboard || hasKeyboardAvoidance) {
+        return (_jsx(View, { style: { flex: 1 }, onStartShouldSetResponderCapture: dismissOnTouchStart, children: content }));
     }
-    return (_jsxs(KeyboardAvoidingView, { style: [{ flex: 1, width: "100%" }, style], behavior: Platform.OS === "ios" ? "padding" : "height", keyboardVerticalOffset: Platform.OS === "ios" ? 0 : 0, children: [content, overlay] }));
+    return (_jsx(KeyboardAvoidingView, { style: [{ flex: 1, width: "100%" }, style], keyboardVerticalOffset: Platform.OS === "ios" ? 0 : 0, onStartShouldSetResponderCapture: dismissOnTouchStart, children: content }));
+}
+function NativeDismissKeyboard(props) {
+    const dismissOnTouchStart = useDismissKeyboardOnOutsideTouch();
+    return (_jsx(DismissKeyboardLayout, { ...props, dismissOnTouchStart: dismissOnTouchStart }));
+}
+/**
+ * @returns Wrapper for a view that dismisses the keyboard when tapped outside of a text input
+ */
+export const DismissKeyboard = (props) => {
+    if (Platform.OS === "web") {
+        return _jsx(DismissKeyboardLayout, { ...props });
+    }
+    return _jsx(NativeDismissKeyboard, { ...props });
 };

package/dist/components/KeyboardAvoidingView.d.ts

@@ -0,0 +1,20 @@
+import React from "react";
+import { type StyleProp, type ViewProps, type ViewStyle } from "react-native";
+type KeyboardAvoidingBehavior = "height" | "padding" | "position" | "translate-with-padding";
+export interface KeyboardAvoidingViewProps extends ViewProps {
+    children: React.ReactNode;
+    style?: StyleProp<ViewStyle>;
+    behavior?: KeyboardAvoidingBehavior;
+    contentContainerStyle?: ViewProps["style"];
+    keyboardVerticalOffset?: number;
+    automaticOffset?: boolean;
+}
+export declare function useKeyboardAvoidance(): boolean;
+/**
+ * Package-level keyboard avoiding wrapper.
+ *
+ * Native uses `react-native-keyboard-controller` so screens can avoid the soft
+ * keyboard with `automaticOffset`; web renders a plain `View`.
+ */
+export declare function KeyboardAvoidingView({ children, style, behavior, automaticOffset, contentContainerStyle, keyboardVerticalOffset, ...props }: KeyboardAvoidingViewProps): React.JSX.Element;
+export {};

package/dist/components/KeyboardAvoidingView.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+import { Platform, View, } from "react-native";
+import { KeyboardAvoidingView as NativeKeyboardAvoidingView, } from "react-native-keyboard-controller";
+const KeyboardAvoidanceContext = createContext(false);
+export function useKeyboardAvoidance() {
+    return useContext(KeyboardAvoidanceContext);
+}
+/**
+ * Package-level keyboard avoiding wrapper.
+ *
+ * Native uses `react-native-keyboard-controller` so screens can avoid the soft
+ * keyboard with `automaticOffset`; web renders a plain `View`.
+ */
+export function KeyboardAvoidingView({ children, style, behavior = Platform.OS === "ios" ? "padding" : "height", automaticOffset = true, contentContainerStyle, keyboardVerticalOffset, ...props }) {
+    if (Platform.OS === "web") {
+        return (_jsx(KeyboardAvoidanceContext.Provider, { value: true, children: _jsx(View, { style: style, ...props, children: children }) }));
+    }
+    return (_jsx(KeyboardAvoidanceContext.Provider, { value: true, children: _jsx(NativeKeyboardAvoidingView, { style: style, behavior: behavior, automaticOffset: automaticOffset, contentContainerStyle: contentContainerStyle, keyboardVerticalOffset: keyboardVerticalOffset, ...props, children: children }) }));
+}

package/dist/components/TextInput.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useImperativeHandle, useMemo, useRef, useState, } from "react";
+import { useEffect, useCallback, useImperativeHandle, useMemo, useRef, useState, } from "react";
 import { StyleSheet, TextInput as RNTextInput, Platform, View, Pressable, } from "react-native";
 import { Host, TextInput as ExpoTextInput, useNativeState, } from "@expo/ui";
 import { useTheme } from "../hooks/useTheme.js";
@@ -9,6 +9,7 @@ import { StyledText } from "./StyledText.js";
 import { Icon } from "./Icon.js";
 import { hapticLight } from "../lib/haptics.js";
 import { palette } from "../constants/colors.js";
+import { clearKeyboardFocusedInputLayout, setKeyboardFocusedInputLayout, } from "./keyboardFocusRegistry.js";
 const NUMERIC_REGEX = /^[0-9]*$/;
 const SIZE_CONFIGS = {
     sm: {
@@ -188,7 +189,7 @@ function WebTextInput({ variant = "outline", size = "md", label, helperText, err
  * elements, and error icon — are intentionally omitted on native to avoid
  * layering RN views over the native host view.
  */
-function NativeTextInput({ variant = "outline", size = "md", label, helperText, errorText, error, required, rows, forceLight, inputMode, onChangeText, value, defaultValue, editable = true, multiline, secureTextEntry, showSecureEntryToggle, ref, wrapperStyle, 
+function NativeTextInput({ variant = "outline", size = "md", label, helperText, errorText, error, required, rows, forceLight, inputMode, onChangeText, onFocus, onBlur, value, defaultValue, editable = true, multiline, secureTextEntry, showSecureEntryToggle, ref, wrapperStyle, 
 // Web-only affordances. Destructured out of `rest` so they're NOT forwarded to
 // the native field; intentionally unused on this path (see doc comment above).
 // `style` (an RN TextStyle) is likewise dropped — it doesn't map to
@@ -220,6 +221,43 @@ leftElement, rightElement, clearable, focusedStyle, style, ...rest }) {
     // We expose the subset consumers use, plus a `setNativeProps` shim so the
     // uncontrolled AuthTextField can push corrected text into the native buffer.
     const innerRef = useRef(null);
+    const surfaceRef = useRef(null);
+    const isFocusedRef = useRef(false);
+    const focusRegistryToken = useMemo(() => ({}), []);
+    const syncFocusedInputLayout = useCallback(() => {
+        if (!isFocusedRef.current)
+            return;
+        surfaceRef.current?.measureInWindow((absoluteX, absoluteY, width, height) => {
+            if (!isFocusedRef.current)
+                return;
+            setKeyboardFocusedInputLayout(focusRegistryToken, {
+                x: 0,
+                y: 0,
+                width,
+                height,
+                absoluteX,
+                absoluteY,
+            }, 
+            // Window-independent dismissal: blur the native field directly. Inside a
+            // native bottom sheet the field lives in its own window, where
+            // `KeyboardController.dismiss()` can miss; calling the field's own ref
+            // always resigns it.
+            () => innerRef.current?.blur());
+        });
+    }, [focusRegistryToken]);
+    const handleFocus = useCallback(() => {
+        isFocusedRef.current = true;
+        syncFocusedInputLayout();
+        onFocus?.();
+    }, [onFocus, syncFocusedInputLayout]);
+    const handleBlur = useCallback(() => {
+        isFocusedRef.current = false;
+        clearKeyboardFocusedInputLayout(focusRegistryToken);
+        onBlur?.();
+    }, [focusRegistryToken, onBlur]);
+    useEffect(() => {
+        return () => clearKeyboardFocusedInputLayout(focusRegistryToken);
+    }, [focusRegistryToken]);
     useImperativeHandle(ref, () => ({
         focus: () => innerRef.current?.focus(),
         blur: () => innerRef.current?.blur(),
@@ -289,7 +327,7 @@ leftElement, rightElement, clearable, focusedStyle, style, ...rest }) {
         fontSize: sizeConfig.fontSize,
         ...(nativeFontFamily ? { fontFamily: nativeFontFamily } : null),
     };
-    return (_jsxs(View, { style: wrapperStyle, children: [!!label && (_jsx(View, { style: styles.labelContainer, children: _jsxs(StyledText, { selectable: false, style: styles.label, children: [label, required && _jsx(StyledText, { selectable: false, style: styles.required, children: " *" })] }) })), _jsxs(View, { style: [surfaceStyle, hasSecureToggle && styles.nativeRow], children: [_jsx(Host, { matchContents: { vertical: true }, style: hasSecureToggle ? styles.nativeHostFlex : styles.nativeHost, children: _jsx(ExpoTextInput, { ...rest, ref: innerRef, value: state, defaultValue: defaultValue, onChangeText: onChangeText, editable: editable, multiline: multiline, rows: rows, inputMode: inputMode, secureTextEntry: effectiveSecureTextEntry, placeholderTextColor: theme.colors.textDim, style: boxStyle, textStyle: textStyle }) }), hasSecureToggle && (_jsx(Pressable, { style: styles.nativePasswordToggle, onPress: () => setPasswordVisible((v) => !v), accessibilityLabel: passwordVisible ? "Hide password" : "Show password", accessibilityRole: "button", children: _jsx(Icon, { name: passwordVisible ? "eye-off" : "eye", size: spacing.iconSm + 4, color: "textDim" }) }))] }), !!(helperText || errorText) && (_jsx(StyledText, { selectable: false, style: [styles.helperText, hasError && styles.errorText], children: errorText || helperText }))] }));
+    return (_jsxs(View, { style: wrapperStyle, children: [!!label && (_jsx(View, { style: styles.labelContainer, children: _jsxs(StyledText, { selectable: false, style: styles.label, children: [label, required && _jsx(StyledText, { selectable: false, style: styles.required, children: " *" })] }) })), _jsxs(View, { ref: surfaceRef, style: [surfaceStyle, hasSecureToggle && styles.nativeRow], onLayout: syncFocusedInputLayout, children: [_jsx(Host, { matchContents: { vertical: true }, style: hasSecureToggle ? styles.nativeHostFlex : styles.nativeHost, children: _jsx(ExpoTextInput, { ...rest, ref: innerRef, value: state, defaultValue: defaultValue, onChangeText: onChangeText, onFocus: handleFocus, onBlur: handleBlur, editable: editable, multiline: multiline, rows: rows, inputMode: inputMode, secureTextEntry: effectiveSecureTextEntry, placeholderTextColor: theme.colors.textDim, style: boxStyle, textStyle: textStyle }) }), hasSecureToggle && (_jsx(Pressable, { style: styles.nativePasswordToggle, onPress: () => setPasswordVisible((v) => !v), accessibilityLabel: passwordVisible ? "Hide password" : "Show password", accessibilityRole: "button", children: _jsx(Icon, { name: passwordVisible ? "eye-off" : "eye", size: spacing.iconSm + 4, color: "textDim" }) }))] }), !!(helperText || errorText) && (_jsx(StyledText, { selectable: false, style: [styles.helperText, hasError && styles.errorText], children: errorText || helperText }))] }));
 }
 const createStyles = (theme, variant, size) => StyleSheet.create({
     nativeHost: {

package/dist/components/UIProvider.d.ts

@@ -1,4 +1,5 @@
 import * as React from "react";
+import { type KeyboardAvoidingViewProps } from "./KeyboardAvoidingView";
 export interface UIProviderProps {
     children: React.ReactNode;
     /**
@@ -19,5 +20,15 @@ export interface UIProviderProps {
      * @default true
      */
     statusBar?: boolean;
+    /**
+     * Wrap app content in the package keyboard-avoiding root.
+     *
+     * @default true on native, false on web
+     */
+    keyboardAvoiding?: boolean;
+    /**
+     * Props forwarded to the keyboard-avoiding root when enabled.
+     */
+    keyboardAvoidingProps?: Omit<KeyboardAvoidingViewProps, "children">;
 }
-export declare function UIProvider({ children, notification, portalHost, statusBar, }: UIProviderProps): React.JSX.Element;
+export declare function UIProvider({ children, notification, portalHost, statusBar, keyboardAvoiding, keyboardAvoidingProps, }: UIProviderProps): React.JSX.Element;

package/dist/components/UIProvider.js

@@ -1,7 +1,11 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Platform } from "react-native";
 import { PortalHost } from "@rn-primitives/portal";
 import { Notification } from "./Notification.js";
 import { StatusBar } from "./StatusBar.js";
-export function UIProvider({ children, notification = true, portalHost = true, statusBar = true, }) {
-    return (_jsxs(_Fragment, { children: [children, notification ? _jsx(Notification, {}) : null, portalHost ? _jsx(PortalHost, {}) : null, statusBar ? _jsx(StatusBar, {}) : null] }));
+import { KeyboardAvoidingView, } from "./KeyboardAvoidingView.js";
+export function UIProvider({ children, notification = true, portalHost = true, statusBar = true, keyboardAvoiding = Platform.OS !== "web", keyboardAvoidingProps, }) {
+    const { style: keyboardAvoidingStyle, ...restKeyboardAvoidingProps } = keyboardAvoidingProps ?? {};
+    const content = keyboardAvoiding ? (_jsx(KeyboardAvoidingView, { style: [{ flex: 1 }, keyboardAvoidingStyle], ...restKeyboardAvoidingProps, children: children })) : (children);
+    return (_jsxs(_Fragment, { children: [content, notification ? _jsx(Notification, {}) : null, portalHost ? _jsx(PortalHost, {}) : null, statusBar ? _jsx(StatusBar, {}) : null] }));
 }

package/dist/components/index.d.ts

@@ -15,6 +15,7 @@ export * from "./EmptyState";
 export * from "./ErrorBoundary";
 export * from "./Icon";
 export * from "./InputOTP";
+export * from "./KeyboardAvoidingView";
 export * from "./Label";
 export * from "./MaxWidthContainer";
 export * from "./Notification";

package/dist/components/index.js

@@ -15,6 +15,7 @@ export * from "./EmptyState.js";
 export * from "./ErrorBoundary.js";
 export * from "./Icon.js";
 export * from "./InputOTP.js";
+export * from "./KeyboardAvoidingView.js";
 export * from "./Label.js";
 export * from "./MaxWidthContainer.js";
 export * from "./Notification.js";

package/dist/components/keyboardFocusRegistry.d.ts

@@ -0,0 +1,29 @@
+import type { GestureResponderEvent } from "react-native";
+import type { FocusedInputLayoutChangedEvent } from "react-native-keyboard-controller";
+export type KeyboardFocusedInputLayout = FocusedInputLayoutChangedEvent["layout"];
+export type KeyboardFocusedInputToken = object;
+/**
+ * Subscribe to focus presence changes. Pairs with {@link hasKeyboardFocusedInput}
+ * via `useSyncExternalStore` so a component can mount/unmount with focus WITHOUT
+ * `react-native-keyboard-controller`'s `useKeyboardState` — which doesn't observe
+ * keyboards raised inside a native sheet's isolated window.
+ */
+export declare function subscribeKeyboardFocus(listener: () => void): () => void;
+export declare function setKeyboardFocusedInputLayout(token: KeyboardFocusedInputToken, layout: KeyboardFocusedInputLayout, blur?: () => void): void;
+export declare function clearKeyboardFocusedInputLayout(token: KeyboardFocusedInputToken): void;
+export declare function getKeyboardFocusedInputLayout(): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    absoluteX: number;
+    absoluteY: number;
+} | undefined;
+/** Whether any native field currently holds focus. Stable boolean for snapshots. */
+export declare function hasKeyboardFocusedInput(): boolean;
+/**
+ * Resign the currently-focused native field, dismissing its keyboard. Returns
+ * `true` if a field was focused and a blur handle was available.
+ */
+export declare function dismissKeyboardFocusedInput(): boolean;
+export declare function isTouchInsideKeyboardFocusedInput(event: GestureResponderEvent, nativeLayout?: KeyboardFocusedInputLayout | null): boolean;

package/dist/components/keyboardFocusRegistry.js

@@ -0,0 +1,64 @@
+const FOCUSED_INPUT_TOUCH_SLOP = 16;
+let focusedInput = null;
+const listeners = new Set();
+function emit() {
+    listeners.forEach((listener) => listener());
+}
+/**
+ * Subscribe to focus presence changes. Pairs with {@link hasKeyboardFocusedInput}
+ * via `useSyncExternalStore` so a component can mount/unmount with focus WITHOUT
+ * `react-native-keyboard-controller`'s `useKeyboardState` — which doesn't observe
+ * keyboards raised inside a native sheet's isolated window.
+ */
+export function subscribeKeyboardFocus(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+export function setKeyboardFocusedInputLayout(token, layout, blur) {
+    const wasPresent = focusedInput != null;
+    focusedInput = { token, layout, blur };
+    // Only notify subscribers on a presence transition; re-measures (scroll,
+    // layout) update the layout silently so the overlay doesn't churn.
+    if (!wasPresent)
+        emit();
+}
+export function clearKeyboardFocusedInputLayout(token) {
+    if (focusedInput?.token === token) {
+        focusedInput = null;
+        emit();
+    }
+}
+export function getKeyboardFocusedInputLayout() {
+    return focusedInput?.layout;
+}
+/** Whether any native field currently holds focus. Stable boolean for snapshots. */
+export function hasKeyboardFocusedInput() {
+    return focusedInput != null;
+}
+/**
+ * Resign the currently-focused native field, dismissing its keyboard. Returns
+ * `true` if a field was focused and a blur handle was available.
+ */
+export function dismissKeyboardFocusedInput() {
+    if (focusedInput?.blur) {
+        focusedInput.blur();
+        return true;
+    }
+    return false;
+}
+function isTouchInsideLayout(event, layout) {
+    if (!layout)
+        return false;
+    const { pageX, pageY } = event.nativeEvent;
+    const left = layout.absoluteX - FOCUSED_INPUT_TOUCH_SLOP;
+    const right = layout.absoluteX + layout.width + FOCUSED_INPUT_TOUCH_SLOP;
+    const top = layout.absoluteY - FOCUSED_INPUT_TOUCH_SLOP;
+    const bottom = layout.absoluteY + layout.height + FOCUSED_INPUT_TOUCH_SLOP;
+    return pageX >= left && pageX <= right && pageY >= top && pageY <= bottom;
+}
+export function isTouchInsideKeyboardFocusedInput(event, nativeLayout) {
+    return (isTouchInsideLayout(event, getKeyboardFocusedInputLayout()) ||
+        isTouchInsideLayout(event, nativeLayout));
+}

package/llms-full.md

@@ -31,10 +31,14 @@ app-local component files.
 Call `useResources()` once near the Expo app root. Mount `UIProvider` once near
 the root when the app uses package feedback or overlay components.
 
-`UIProvider` owns the package `Notification`, `StatusBar`, and default
-`@rn-primitives` portal host. Mount it before using `Dialog`, `AlertDialog`,
-`BottomSheet`, `Drawer`, `DropdownMenu`, `Popover`, `SelectContent`,
-`Tooltip`, or `notify` / `globalUIStore` notifications.
+`UIProvider` owns the package `Notification`, `StatusBar`, default
+`@rn-primitives` portal host, and native keyboard-avoiding root. Mount it
+before using `Dialog`, `AlertDialog`, `BottomSheet`, `Drawer`, `DropdownMenu`,
+`Popover`, `SelectContent`, `Tooltip`, or `notify` / `globalUIStore`
+notifications. Pass `keyboardAvoiding={false}` to opt out of the native root
+keyboard avoidance, or use `KeyboardAvoidingView` directly for a subtree with
+custom behavior. Web skips the root keyboard wrapper unless `keyboardAvoiding`
+is explicitly enabled.
 
 On native, `BottomSheet.Content` composes its sheet transform with React Native
 keyboard event values. Pass `avoidKeyboard={false}` for sheets that should not
@@ -99,6 +103,7 @@ Use this catalog before creating a new app-local primitive.
 | `ErrorBoundary` | `@mrmeg/expo-ui/components` | React render error fallback | Use for route or feature boundaries. |
 | `Icon` | `@mrmeg/expo-ui/components` | Feather or custom icons with theme tokens | Avoid raw vector icons with hardcoded colors. |
 | `InputOTP` | `@mrmeg/expo-ui/components` | Verification code entry | Prefer over manually managed text input groups. |
+| `KeyboardAvoidingView` | `@mrmeg/expo-ui/components` | Native keyboard-aware layout roots, composer footers, and form-heavy subtrees | `UIProvider` already mounts one root by default; use this directly only for custom subtrees. |
 | `Label` | `@mrmeg/expo-ui/components` | Accessible form labels | Use with package form controls. |
 | `MaxWidthContainer` | `@mrmeg/expo-ui/components` | Centered responsive width | Use for web and tablet constrained layouts. |
 | `Notification` | `@mrmeg/expo-ui/components` | Global toast surface | Trigger through `notify` (or `globalUIStore` for subscriptions/tests) with root `UIProvider`; optional actions dismiss after press. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrmeg/expo-ui",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [