@mrmeg/expo-ui 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 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

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/DismissKeyboard.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Pressable, StyleSheet, Platform, KeyboardAvoidingView, ScrollView, View, } from "react-native";
+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.
@@ -21,18 +22,24 @@ function KeyboardDismissOverlay() {
     const isVisible = useKeyboardState((state) => state.isVisible);
     if (!isVisible)
         return null;
-    return (_jsx(Pressable, { style: StyleSheet.absoluteFill, onPress: () => KeyboardController.dismiss(), accessibilityLabel: "Dismiss keyboard", accessibilityRole: "button" }));
+    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);
     // 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) {
+    if (!avoidKeyboard || hasKeyboardAvoidance) {
         return (_jsxs(View, { style: { flex: 1 }, children: [content, overlay] }));
     }
-    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 (_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/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.11.0",
+  "version": "0.12.0",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [