@mrmeg/expo-ui 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -3,6 +3,54 @@
 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.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
+
+- **New peer dependency: `react-native-keyboard-controller` (>=1.21.0 <2.0.0).**
+  Required by `DismissKeyboard` to dismiss the software keyboard for the native
+  `@expo/ui` TextInput (see fix below). It ships a no-op web fallback, so web
+  bundles are unaffected.
+
+### Fixed
+
+- **`DismissKeyboard` now dismisses the keyboard for native `@expo/ui` fields.**
+  The native TextInput is a SwiftUI / Compose field that never registers with
+  React Native's `TextInputState`, so the previous `Keyboard.dismiss()` (which
+  only blurs RN-tracked inputs) did nothing — tapping outside never closed the
+  keyboard on iOS or Android. `DismissKeyboard` now mounts a full-screen
+  tap-catcher *only while the keyboard is visible* (`useKeyboardState`) that calls
+  `KeyboardController.dismiss()` at the IME level. Mounting it only while visible
+  avoids stealing the focus tap and fighting bottom sheets / modals. Web remains a
+  no-op (no software keyboard); all existing props (`children`, `style`,
+  `avoidKeyboard`, `scrollable`) and the `KeyboardAvoidingView` / `ScrollView`
+  wrapping behavior are preserved.
+- **Android: TextInput text is now vertically centered.** The native field set a
+  fixed `height`, but Android's Compose `BasicTextField` decoration box defaults to
+  `contentAlignment = topStart`, so text pinned to the top with the slack falling to
+  the bottom (iOS centered fine). The single-line field is now sized by symmetric
+  vertical padding instead of a fixed height, centering the text on Android with no
+  change to iOS sizing or centering. Multiline is unchanged.
+
 ## [0.10.1]
 
 ### Fixed

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.d.ts

@@ -15,7 +15,9 @@ import { ViewProps, StyleProp, ViewStyle, ScrollViewProps } from "react-native";
  *
  * Platform-owned behaviors (props accepted for ergonomics, but the platform
  * decides):
- *   - `.Handle` is a no-op: the platform draws the drag indicator.
+ *   - `.Handle` replaces the native drag indicator with a pressable equivalent.
+ *     Pressing it walks through the configured snap points, reversing direction
+ *     at either end. Dragging the sheet continues to use the platform gesture.
  *   - `swipeEnabled` / `avoidKeyboard` / `dismissKeyboardOnDrag` are accepted
  *     for call-site ergonomics but have no effect — the platform handles them.
  *   - Sheet *chrome* (corner radius, system background, safe area) is the
@@ -59,6 +61,9 @@ interface BottomSheetContextValue {
     onOpenChange: (open: boolean) => void;
     toggle: () => void;
     snapPoints: SnapPoint[];
+    snapIndex: number;
+    setSnapIndex: (index: number) => void;
+    cycleSnapPoint: () => void;
     closeOnBackdropPress: boolean;
     /**
      * True when a `Body`'s content overflows its viewport (is genuinely
@@ -136,7 +141,7 @@ declare function useBottomSheetContext(): BottomSheetContextValue;
 declare function BottomSheetRoot({ open: controlledOpen, onOpenChange: controlledOnOpenChange, defaultOpen, snapPoints, closeOnBackdropPress, children, }: BottomSheetProps): React.JSX.Element;
 declare function BottomSheetTrigger({ asChild, children, style: styleOverride }: BottomSheetTriggerProps): React.JSX.Element;
 declare function BottomSheetContent({ swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDrag: _dismissKeyboardOnDrag, style: styleOverride, children, }: BottomSheetContentProps): React.JSX.Element;
-declare function BottomSheetHandle(_props: BottomSheetHandleProps): null;
+declare function BottomSheetHandle({ style }: BottomSheetHandleProps): React.JSX.Element;
 declare function BottomSheetHeader({ children, style, ...props }: BottomSheetHeaderProps): React.JSX.Element;
 declare function BottomSheetBody({ children, style, contentContainerStyle, onContentSizeChange, onLayout, ...props }: BottomSheetBodyProps): React.JSX.Element;
 declare function BottomSheetFooter({ children, style, ...props }: BottomSheetFooterProps): React.JSX.Element;

package/dist/components/BottomSheet.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import React, { createContext, use, useCallback, useEffect, useRef, useState } from "react";
+import React, { createContext, use, useCallback, useEffect, useReducer, useRef } from "react";
 import { View, Pressable, ScrollView, Platform, useWindowDimensions, } from "react-native";
 import { BottomSheet as NativeBottomSheet } from "@expo/ui/community/bottom-sheet";
 import { useSafeAreaInsets, initialWindowMetrics } from "react-native-safe-area-context";
@@ -7,6 +7,62 @@ import { useTheme } from "../hooks/useTheme.js";
 import { spacing } from "../constants/spacing.js";
 import { TextColorContext, TextClassContext } from "./StyledText.context";
 import { Icon } from "./Icon.js";
+function clampSnapIndex(index, maxSnapIndex) {
+    return Math.min(Math.max(index, 0), maxSnapIndex);
+}
+function createInitialRootState(defaultOpen, maxSnapIndex) {
+    return {
+        internalOpen: defaultOpen,
+        scrollable: false,
+        hasHeader: false,
+        hasFooter: false,
+        snapIndex: maxSnapIndex,
+        snapDirection: -1,
+    };
+}
+function bottomSheetRootReducer(state, action) {
+    switch (action.type) {
+        case "setInternalOpen":
+            return {
+                ...state,
+                internalOpen: action.open,
+                snapIndex: action.open ? state.snapIndex : action.maxSnapIndex,
+                snapDirection: action.open ? state.snapDirection : -1,
+            };
+        case "setScrollable":
+            return { ...state, scrollable: action.scrollable };
+        case "setHasHeader":
+            return { ...state, hasHeader: action.present };
+        case "setHasFooter":
+            return { ...state, hasFooter: action.present };
+        case "setSnapIndex": {
+            const snapIndex = clampSnapIndex(action.index, action.maxSnapIndex);
+            return {
+                ...state,
+                snapIndex,
+                snapDirection: snapIndex === 0 ? 1 : snapIndex === action.maxSnapIndex ? -1 : state.snapDirection,
+            };
+        }
+        case "cycleSnapPoint": {
+            if (action.maxSnapIndex === 0)
+                return state;
+            if (action.android) {
+                const snapIndex = state.snapIndex === action.maxSnapIndex ? 0 : action.maxSnapIndex;
+                return { ...state, snapIndex, snapDirection: snapIndex === 0 ? 1 : -1 };
+            }
+            let snapDirection = state.snapDirection;
+            if (state.snapIndex <= 0)
+                snapDirection = 1;
+            if (state.snapIndex >= action.maxSnapIndex)
+                snapDirection = -1;
+            return {
+                ...state,
+                snapIndex: state.snapIndex + snapDirection,
+                snapDirection,
+            };
+        }
+    }
+}
 // ============================================================================
 // Context
 // ============================================================================
@@ -87,33 +143,45 @@ function SheetCloseButton({ style }) {
 // Root
 // ============================================================================
 function BottomSheetRoot({ open: controlledOpen, onOpenChange: controlledOnOpenChange, defaultOpen = false, snapPoints = ["50%"], closeOnBackdropPress = true, children, }) {
-    const [internalOpen, setInternalOpen] = useState(defaultOpen);
-    const [scrollable, setScrollable] = useState(false);
-    const [hasHeader, setHasHeader] = useState(false);
-    const [hasFooter, setHasFooter] = useState(false);
+    const maxSnapIndex = Math.max(snapPoints.length - 1, 0);
+    const [state, dispatch] = useReducer(bottomSheetRootReducer, undefined, () => createInitialRootState(defaultOpen, maxSnapIndex));
     const isControlled = controlledOpen !== undefined;
-    const open = isControlled ? controlledOpen : internalOpen;
-    const onOpenChange = (newOpen) => {
+    const open = isControlled ? controlledOpen : state.internalOpen;
+    const snapIndex = clampSnapIndex(state.snapIndex, maxSnapIndex);
+    const setSnapIndex = useCallback((index) => {
+        dispatch({ type: "setSnapIndex", index, maxSnapIndex });
+    }, [maxSnapIndex]);
+    const cycleSnapPoint = useCallback(() => {
+        dispatch({
+            type: "cycleSnapPoint",
+            maxSnapIndex,
+            android: Platform.OS === "android",
+        });
+    }, [maxSnapIndex]);
+    const onOpenChange = useCallback((newOpen) => {
         if (isControlled) {
             controlledOnOpenChange?.(newOpen);
         }
         else {
-            setInternalOpen(newOpen);
+            dispatch({ type: "setInternalOpen", open: newOpen, maxSnapIndex });
         }
-    };
-    const toggle = () => onOpenChange(!open);
+    }, [controlledOnOpenChange, isControlled, maxSnapIndex]);
+    const toggle = useCallback(() => onOpenChange(!open), [onOpenChange, open]);
     const contextValue = {
         open,
         onOpenChange,
         toggle,
         snapPoints,
+        snapIndex,
+        setSnapIndex,
+        cycleSnapPoint,
         closeOnBackdropPress,
-        scrollable,
-        setScrollable,
-        hasHeader,
-        setHasHeader,
-        hasFooter,
-        setHasFooter,
+        scrollable: state.scrollable,
+        setScrollable: (scrollable) => dispatch({ type: "setScrollable", scrollable }),
+        hasHeader: state.hasHeader,
+        setHasHeader: (present) => dispatch({ type: "setHasHeader", present }),
+        hasFooter: state.hasFooter,
+        setHasFooter: (present) => dispatch({ type: "setHasFooter", present }),
     };
     return (_jsx(BottomSheetContext.Provider, { value: contextValue, children: children }));
 }
@@ -141,14 +209,14 @@ function BottomSheetTrigger({ asChild, children, style: styleOverride }) {
 function BottomSheetContent({ 
 // Accepted-but-ignored ergonomics props (platform owns these behaviors):
 swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDrag: _dismissKeyboardOnDrag, style: styleOverride, children, }) {
-    const { open, onOpenChange, snapPoints, hasHeader } = useBottomSheetContext();
+    const { open, onOpenChange, snapPoints, snapIndex, setSnapIndex, hasHeader } = useBottomSheetContext();
     const { theme } = useTheme();
     const dismissDisabled = useDismissDisabled();
     const showClose = useShowClose();
     const { height: winH } = useWindowDimensions();
-    // Boolean open → native imperative index. Open at the highest snap point so
-    // the sheet starts fully expanded; -1 keeps it closed.
-    const index = open ? snapPoints.length - 1 : -1;
+    // Boolean open → native imperative index. The root resets snapIndex to the
+    // highest point while closed; -1 keeps the native sheet closed.
+    const index = open ? snapIndex : -1;
     // The native RN-in-SwiftUI host does NOT clamp our RN column to the sheet's
     // detent height — it lays the column out at its full intrinsic content height,
     // SwiftUI then clips it at the sheet edge (footer/tail fall off-screen), and
@@ -163,12 +231,21 @@ swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDra
     // dismiss is off, or the body scrolls), float one over the top-right corner.
     // A Header, when present, renders its own (see BottomSheetHeader).
     const showFloatingClose = showClose && !hasHeader;
+    const hasInteractiveHandle = containsHandle(children);
     const handleChange = (newIndex) => {
         // Native fires onChange(-1) on dismiss (swipe / backdrop / back button).
-        if (newIndex < 0 && open)
-            onOpenChange(false);
+        if (newIndex < 0) {
+            if (open)
+                onOpenChange(false);
+            return;
+        }
+        setSnapIndex(newIndex);
     };
-    return (_jsx(NativeBottomSheet, { index: index, snapPoints: snapPoints, enablePanDownToClose: !dismissDisabled, onChange: handleChange, onClose: () => {
+    return (_jsx(NativeBottomSheet, { index: index, snapPoints: snapPoints, 
+        // The native indicator lives outside the hosted RN tree and cannot
+        // receive JS presses. Hide it only when the compound Handle supplies the
+        // interactive replacement; sheets without Handle retain native chrome.
+        handleComponent: hasInteractiveHandle ? null : undefined, enablePanDownToClose: !dismissDisabled, onChange: handleChange, onClose: () => {
             if (open)
                 onOpenChange(false);
         }, 
@@ -191,10 +268,37 @@ swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDra
                             } }))] }) }) }) }));
 }
 // ============================================================================
-// Handle — no-op (the platform draws the drag indicator)
+// Handle — pressable snap-point control; native drag gestures remain active
 // ============================================================================
-function BottomSheetHandle(_props) {
-    return null;
+/** Walk a React children tree looking for a `BottomSheet.Handle` element. */
+function containsHandle(node) {
+    return React.Children.toArray(node).some((child) => {
+        if (!React.isValidElement(child))
+            return false;
+        if (child.type === BottomSheetHandle)
+            return true;
+        return containsHandle(child.props.children);
+    });
+}
+function BottomSheetHandle({ style }) {
+    const { cycleSnapPoint, snapPoints } = useBottomSheetContext();
+    const { theme } = useTheme();
+    const disabled = snapPoints.length < 2;
+    return (_jsx(Pressable, { accessibilityRole: "button", accessibilityLabel: "Change sheet height", accessibilityHint: "Moves the sheet to the next snap point", accessibilityState: { disabled }, disabled: disabled, onPress: cycleSnapPoint, style: ({ pressed }) => [
+            {
+                minHeight: spacing.touchTarget,
+                alignItems: "center",
+                justifyContent: "center",
+                opacity: pressed ? 0.65 : 1,
+            },
+            Platform.OS === "web" && !disabled && { cursor: "pointer" },
+            style,
+        ], children: _jsx(View, { style: {
+                width: spacing.xl,
+                height: spacing.xs,
+                borderRadius: spacing.radiusFull,
+                backgroundColor: theme.colors.mutedForeground,
+            } }) }));
 }
 // ============================================================================
 // Header

package/dist/components/DismissKeyboard.js

@@ -1,13 +1,45 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { Pressable, Keyboard, Platform, KeyboardAvoidingView, ScrollView } from "react-native";
-const handleDismissKeyboard = () => Platform.OS !== "web" && Keyboard.dismiss();
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Pressable, StyleSheet, Platform, ScrollView, View, } from "react-native";
+import { KeyboardController, useKeyboardState } from "react-native-keyboard-controller";
+import { KeyboardAvoidingView, useKeyboardAvoidance } from "./KeyboardAvoidingView.js";
+/**
+ * Full-screen tap-catcher that dismisses the keyboard, mounted ONLY while the
+ * keyboard is visible.
+ *
+ * Why window-level dismissal: the native `@expo/ui` TextInput is a SwiftUI /
+ * Compose field that never registers with React Native's `TextInputState`, so
+ * `Keyboard.dismiss()` (which only blurs RN-tracked inputs) does nothing for it.
+ * `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.
+ */
+function KeyboardDismissOverlay() {
+    const isVisible = useKeyboardState((state) => state.isVisible);
+    if (!isVisible)
+        return null;
+    return (_jsx(Pressable, { style: [StyleSheet.absoluteFill, styles.overlay], onPressIn: () => KeyboardController.dismiss(), accessibilityLabel: "Dismiss keyboard", accessibilityRole: "button" }));
+}
 /**
  * @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 }) => {
+    const hasKeyboardAvoidance = useKeyboardAvoidance();
     const content = scrollable ? (_jsx(ScrollView, { style: { flex: 1 }, contentContainerStyle: { flexGrow: 1, justifyContent: "center" }, keyboardShouldPersistTaps: "handled", showsVerticalScrollIndicator: false, children: children })) : (children);
-    if (!avoidKeyboard) {
-        return (_jsx(Pressable, { onPress: handleDismissKeyboard, accessible: false, style: { flex: 1 }, children: content }));
+    // 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 || hasKeyboardAvoidance) {
+        return (_jsxs(View, { style: { flex: 1 }, children: [content, overlay] }));
     }
-    return (_jsx(KeyboardAvoidingView, { style: [{ flex: 1, width: "100%" }, style], behavior: Platform.OS === "ios" ? "padding" : "height", keyboardVerticalOffset: Platform.OS === "ios" ? 0 : 0, children: _jsx(Pressable, { onPress: handleDismissKeyboard, accessible: false, style: { flex: 1 }, children: content }) }));
+    return (_jsxs(KeyboardAvoidingView, { style: [{ flex: 1, width: "100%" }, style], keyboardVerticalOffset: Platform.OS === "ios" ? 0 : 0, children: [content, overlay] }));
 };
+const styles = StyleSheet.create({
+    overlay: {
+        zIndex: 999,
+    },
+});

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

@@ -16,18 +16,21 @@ const SIZE_CONFIGS = {
         fontSize: 13,
         paddingVertical: spacing.xs,
         paddingHorizontal: spacing.sm,
+        nativePaddingVertical: 7,
     },
     md: {
         height: 36,
         fontSize: 14,
         paddingVertical: spacing.xs,
         paddingHorizontal: spacing.sm,
+        nativePaddingVertical: 8,
     },
     lg: {
         height: 40,
         fontSize: 15,
         paddingVertical: spacing.sm,
         paddingHorizontal: spacing.md,
+        nativePaddingVertical: 10,
     },
 };
 /**
@@ -257,13 +260,21 @@ leftElement, rightElement, clearable, focusedStyle, style, ...rest }) {
         opacity: editable === false ? 0.6 : 1,
         overflow: "hidden",
     };
-    // Native field: transparent, padding + height only. The visible surface is
-    // drawn by `surfaceStyle` on the wrapper above.
+    // Native field: transparent, padding only. The visible surface is drawn by
+    // `surfaceStyle` on the wrapper above.
+    //
+    // Single-line height comes from symmetric vertical padding, NOT a fixed
+    // `height`. Forcing a height made Android pin the text to the top of the box
+    // (Compose's decoration box uses `contentAlignment = topStart`), leaving a
+    // bottom-heavy gap; iOS centered fine. Letting padding define the height keeps
+    // the text vertically centered on both platforms while matching the previous
+    // visual size (≈ `sizeConfig.height`). Multiline is left to grow naturally.
     const boxStyle = {
         backgroundColor: "transparent",
         paddingHorizontal: sizeConfig.paddingHorizontal,
-        paddingVertical: sizeConfig.paddingVertical,
-        ...(multiline ? null : { height: sizeConfig.height }),
+        paddingVertical: multiline
+            ? sizeConfig.paddingVertical
+            : sizeConfig.nativePaddingVertical,
     };
     // "System" is an RN-only sentinel (RCTFont resolves it to the system font).
     // @expo/ui passes the family verbatim to SwiftUI's Font.custom / Compose,

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/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.10.1",
+  "version": "0.12.0",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [
@@ -117,6 +117,7 @@
     "react": ">=19.2.0 <20.0.0",
     "react-native": ">=0.83.0 <0.86.0",
     "react-native-gesture-handler": ">=2.30.0 <2.32.0",
+    "react-native-keyboard-controller": ">=1.21.0 <2.0.0",
     "react-native-safe-area-context": ">=5.6.0 <6.0.0",
     "react-native-screens": ">=4.23.0 <5.0.0",
     "react-native-web": ">=0.21.0 <0.22.0",
@@ -124,6 +125,7 @@
   },
   "devDependencies": {
     "@types/react": "~19.2.17",
+    "react-native-keyboard-controller": "1.21.6",
     "typescript": "~6.0.3"
   }
 }