@mrmeg/expo-ui 0.1.10 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Megenhardt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LLM_USAGE.md

@@ -68,6 +68,11 @@ export function RootLayout() {
 `AlertDialog`, `BottomSheet`, `Drawer`, `DropdownMenu`, `Popover`,
 `SelectContent`, or `Tooltip`.
 
+On native, `BottomSheet.Content` avoids the soft keyboard by default through
+`react-native-keyboard-controller`. Mount that library's `KeyboardProvider`
+near the app root before using bottom sheets with text inputs, or pass
+`avoidKeyboard={false}` to opt out for a specific sheet.
+
 i18n is optional. Do not add app-level i18n setup just to use this package.
 Plain children and `text` props work without `i18next` or `react-i18next`.
 `tx` props render fallback text when provided and otherwise render the key
@@ -154,7 +159,7 @@ Use this table before creating a new app-local primitive.
 | `Alert` | Cross-platform imperative alerts | Direct `window.alert` or duplicated RN/web branching | Confirm destructive actions, native alert dialogs |
 | `AnimatedView` | Entrance and visibility animation | Hand-rolled Reanimated wrappers | Staggered list rows, revealed panels, animated empty states |
 | `Badge` | Short status labels | Custom pill `View` + `Text` | Draft/active states, counts, plan labels, role tags |
-| `BottomSheet` | Mobile-first modal sheets | Custom absolute-position sheets | Action pickers, mobile filters, quick edit forms |
+| `BottomSheet` | Mobile-first modal sheets | Custom absolute-position sheets | Action pickers, mobile filters, keyboard-aware quick edit forms |
 | `Button` | Commands and CTAs | Pressable plus custom text styling | Submit, save, cancel, delete, navigation CTAs |
 | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` | Framed content groups | Ad hoc bordered panels | List items, pricing plans, settings sections, summaries |
 | `Checkbox` | Boolean selection | Custom checkmark controls | Terms consent, checklist items, multi-select filters |

package/README.md

@@ -31,8 +31,11 @@ Consumers must also install the native and Expo peer dependencies listed in
 `package.json`. The tested baseline is Expo SDK 55 with React 19.2, React
 Native 0.83, React Native Web 0.21, Reanimated 4.2, and Worklets 0.7.
 `@rn-primitives/*` packages are managed by `@mrmeg/expo-ui` because they are
-implementation details of the exported UI components. i18n setup is optional;
-plain text and children render without `i18next` or `react-i18next`. Start
+implementation details of the exported UI components. Native bottom sheet
+keyboard avoidance uses `react-native-keyboard-controller`; mount that
+library's `KeyboardProvider` near the app root when sheets contain text
+inputs. i18n setup is optional; plain text and children render without
+`i18next` or `react-i18next`. Start
 consumer apps from the same Expo SDK family or update the package and peer
 ranges deliberately. Keep npm auth tokens in developer or CI configuration,
 not in this repository.
@@ -165,7 +168,7 @@ All components are exported from `@mrmeg/expo-ui/components`; direct imports suc
 | `Alert` | Cross-platform imperative alerts | Direct `window.alert` or duplicated RN/web branching | Confirm destructive actions, native alert dialogs, simple blocking messages |
 | `AnimatedView` | Entrance and visibility animation | Hand-rolled Reanimated wrappers | Staggered list rows, revealed panels, animated empty states |
 | `Badge` | Short status labels | Custom pill `View` + `Text` | Draft/active states, counts, plan labels, role tags |
-| `BottomSheet` | Mobile-first modal sheets | Custom absolute-position sheets | Action pickers, mobile filters, quick edit forms, contextual details |
+| `BottomSheet` | Mobile-first modal sheets | Custom absolute-position sheets | Action pickers, mobile filters, keyboard-aware quick edit forms, contextual details |
 | `Button` | Commands and CTAs | Pressable plus custom text styling | Submit, save, cancel, delete, navigation CTAs, icon-accessory buttons; loading state preserves resting width |
 | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` | Framed content groups | Ad hoc bordered panels | List items, pricing plans, settings sections, summaries, dashboards |
 | `Checkbox` | Boolean selection | Custom checkmark controls | Terms consent, checklist items, multi-select filters, notification opt-ins |
@@ -228,7 +231,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. Trigger transient feedback from `globalUIStore`.
+Mount `UIProvider` once near the root before using `Dialog`, `AlertDialog`, `BottomSheet`, `Drawer`, `DropdownMenu`, `Popover`, `SelectContent`, `Tooltip`, or package notifications. On native, mount `KeyboardProvider` from `react-native-keyboard-controller` near the root before using `BottomSheet.Content` with text inputs; `avoidKeyboard` defaults to `true` and can be disabled per sheet. Trigger transient feedback from `globalUIStore`.
 
 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

@@ -32,6 +32,10 @@ interface BottomSheetContentProps extends ViewProps {
     swipeEnabled?: boolean;
     /** Velocity threshold for quick swipe to close */
     velocityThreshold?: number;
+    /** Whether to move the sheet with the native keyboard animation. Default: true. */
+    avoidKeyboard?: boolean;
+    /** Whether to dismiss the keyboard when a native drag starts. Default: true. */
+    dismissKeyboardOnDrag?: boolean;
     style?: StyleProp<ViewStyle>;
     children: React.ReactNode;
 }
@@ -55,7 +59,7 @@ interface BottomSheetCloseProps {
 declare function useBottomSheetContext(): BottomSheetContextValue;
 declare function BottomSheetRoot({ open: controlledOpen, onOpenChange: controlledOnOpenChange, defaultOpen, snapPoints: rawSnapPoints, closeOnBackdropPress, children, }: BottomSheetProps): import("react/jsx-runtime").JSX.Element;
 declare function BottomSheetTrigger({ asChild, children, style: styleOverride }: BottomSheetTriggerProps): import("react/jsx-runtime").JSX.Element;
-declare function BottomSheetContent({ swipeEnabled, velocityThreshold, style: styleOverride, children, ...props }: BottomSheetContentProps): import("react/jsx-runtime").JSX.Element | null;
+declare function BottomSheetContent({ swipeEnabled, velocityThreshold, avoidKeyboard, dismissKeyboardOnDrag, style: styleOverride, children, ...props }: BottomSheetContentProps): import("react/jsx-runtime").JSX.Element | null;
 declare function BottomSheetHandle({ style }: BottomSheetHandleProps): import("react/jsx-runtime").JSX.Element;
 declare function BottomSheetHeader({ children, style, ...props }: BottomSheetHeaderProps): import("react/jsx-runtime").JSX.Element;
 declare function BottomSheetBody({ children, style, ...props }: BottomSheetBodyProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/BottomSheet.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import React, { createContext, useCallback, useContext, useEffect, useReducer, useRef, useState } from "react";
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useReducer, useRef, useState } from "react";
 import { View, Pressable, Animated, StyleSheet, Platform, Dimensions, PanResponder, ScrollView, } from "react-native";
 import { Portal } from "@rn-primitives/portal";
 import { FullWindowOverlay as RNFullWindowOverlay } from "react-native-screens";
 import { Pressable as SlotPressable } from "@rn-primitives/slot";
+import { KeyboardController, useKeyboardAnimation } from "react-native-keyboard-controller";
 import { useTheme } from "../hooks/useTheme.js";
 import { spacing } from "../constants/spacing.js";
 import { shouldUseNativeDriver } from "../lib/animations.js";
@@ -50,6 +51,20 @@ function useBottomSheetContext() {
     return context;
 }
 const DragContext = createContext(null);
+function BottomSheetPanel({ accessibilityViewIsModal, children, panHandlers, sheetStyle, styleOverride, translateY, ...props }) {
+    return (_jsx(Animated.View, { style: [
+            sheetStyle,
+            { transform: [{ translateY }] },
+            styleOverride && typeof styleOverride !== "function"
+                ? StyleSheet.flatten(styleOverride)
+                : undefined,
+        ], accessibilityViewIsModal: accessibilityViewIsModal, ...panHandlers, ...props, children: children }));
+}
+function KeyboardAvoidingBottomSheetPanel(props) {
+    const { height: keyboardHeight } = useKeyboardAnimation();
+    const composedTranslateY = useMemo(() => Animated.add(props.translateY, keyboardHeight), [keyboardHeight, props.translateY]);
+    return _jsx(BottomSheetPanel, { ...props, translateY: composedTranslateY });
+}
 // ============================================================================
 // Utility Functions
 // ============================================================================
@@ -126,7 +141,7 @@ function BottomSheetTrigger({ asChild, children, style: styleOverride }) {
 // ============================================================================
 // Content
 // ============================================================================
-function BottomSheetContent({ swipeEnabled = true, velocityThreshold = 500, style: styleOverride, children, ...props }) {
+function BottomSheetContent({ swipeEnabled = true, velocityThreshold = 500, avoidKeyboard = true, dismissKeyboardOnDrag = true, style: styleOverride, children, ...props }) {
     const sheetContext = useBottomSheetContext();
     const { open, onOpenChange, snapPoints, closeOnBackdropPress } = sheetContext;
     const { theme } = useTheme();
@@ -224,6 +239,11 @@ function BottomSheetContent({ swipeEnabled = true, velocityThreshold = 500, styl
         const progress = 1 - dragFromBase / currentHeightRef.current;
         backdropOpacity.setValue(Math.max(0, progress));
     }, [translateY, backdropOpacity, maxHeight]);
+    const dismissKeyboardForDrag = useCallback(() => {
+        if (Platform.OS !== "web" && dismissKeyboardOnDrag) {
+            void KeyboardController.dismiss();
+        }
+    }, [dismissKeyboardOnDrag]);
     // ------------------------------------------------------------------
     // Trigger animation during render if open changed
     // ------------------------------------------------------------------
@@ -287,7 +307,7 @@ function BottomSheetContent({ swipeEnabled = true, velocityThreshold = 500, styl
     // ------------------------------------------------------------------
     // Native: PanResponder for swipe gestures on the whole sheet
     // ------------------------------------------------------------------
-    const panResponder = useRef(Platform.OS !== "web" && swipeEnabled
+    const panResponder = useMemo(() => Platform.OS !== "web" && swipeEnabled
         ? PanResponder.create({
             onStartShouldSetPanResponder: () => false,
             onMoveShouldSetPanResponder: (_evt, gestureState) => {
@@ -296,6 +316,7 @@ function BottomSheetContent({ swipeEnabled = true, velocityThreshold = 500, styl
                 const isDownward = gestureState.dy > 0;
                 return isVertical && isSignificant && isDownward;
             },
+            onPanResponderGrant: dismissKeyboardForDrag,
             onPanResponderMove: (_evt, gestureState) => {
                 handleDragMove(gestureState.dy);
             },
@@ -303,7 +324,7 @@ function BottomSheetContent({ swipeEnabled = true, velocityThreshold = 500, styl
                 handleDragRelease(Math.max(0, gestureState.dy), gestureState.vy);
             },
         })
-        : null).current;
+        : null, [dismissKeyboardForDrag, handleDragMove, handleDragRelease, swipeEnabled]);
     // ------------------------------------------------------------------
     // Web: drag context provides callbacks for Handle's pointer events
     // ------------------------------------------------------------------
@@ -339,6 +360,9 @@ function BottomSheetContent({ swipeEnabled = true, velocityThreshold = 500, styl
         ...(Platform.OS === "web" && { zIndex: 51 }),
     };
     const sheetContent = (_jsx(TextColorContext.Provider, { value: textColor, children: _jsx(TextClassContext.Provider, { value: "", children: children }) }));
+    const PanelComponent = Platform.OS !== "web" && avoidKeyboard
+        ? KeyboardAvoidingBottomSheetPanel
+        : BottomSheetPanel;
     const contentElement = (_jsx(Portal, { name: "bottom-sheet-portal", children: _jsx(FullWindowOverlay, { children: _jsx(BottomSheetContext.Provider, { value: sheetContext, children: _jsxs(View, { style: StyleSheet.absoluteFill, children: [_jsx(Animated.View, { style: [
                                 StyleSheet.absoluteFill,
                                 {
@@ -346,16 +370,10 @@ function BottomSheetContent({ swipeEnabled = true, velocityThreshold = 500, styl
                                     opacity: backdropOpacity,
                                 },
                                 Platform.OS === "web" && { zIndex: 50 },
-                            ], children: _jsx(Pressable, { style: StyleSheet.absoluteFill, onPress: handleBackdropPress }) }), _jsx(Animated.View, { style: [
-                                sheetStyle,
-                                { transform: [{ translateY }] },
-                                styleOverride && typeof styleOverride !== "function"
-                                    ? StyleSheet.flatten(styleOverride)
-                                    : undefined,
-                            ], accessibilityViewIsModal: true, ...(Platform.OS === "web" && {
+                            ], children: _jsx(Pressable, { style: StyleSheet.absoluteFill, onPress: handleBackdropPress }) }), _jsx(PanelComponent, { sheetStyle: sheetStyle, styleOverride: styleOverride, translateY: translateY, accessibilityViewIsModal: true, ...(Platform.OS === "web" && {
                                 role: "dialog",
                                 "aria-modal": true,
-                            }), ...(panResponder ? panResponder.panHandlers : {}), ...props, children: dragContextValue ? (_jsx(DragContext.Provider, { value: dragContextValue, children: sheetContent })) : (sheetContent) })] }) }) }) }));
+                            }), panHandlers: panResponder ? panResponder.panHandlers : undefined, ...props, children: dragContextValue ? (_jsx(DragContext.Provider, { value: dragContextValue, children: sheetContent })) : (sheetContent) })] }) }) }) }));
     return contentElement;
 }
 // ============================================================================

package/dist/components/Button.js

@@ -257,7 +257,7 @@ const createStyles = (theme, size) => {
             marginLeft: spacing.sm,
         },
         loaderOverlay: {
-            ...StyleSheet.absoluteFillObject,
+            ...StyleSheet.absoluteFill,
             alignItems: "center",
             justifyContent: "center",
         },

package/dist/components/Switch.js

@@ -77,7 +77,7 @@ function Switch({ variant = "default", labelOn, labelOff, size = { width: 44, he
             disabled: !!props.disabled,
             busy: loading,
         }, children: [_jsx(View, { style: {
-                    ...StyleSheet.absoluteFillObject,
+                    ...StyleSheet.absoluteFill,
                     borderRadius: size.height / 2,
                     backgroundColor: trackBg,
                     borderWidth: 1,

package/dist/hooks/useScalePress.d.ts

@@ -43,11 +43,11 @@ interface ScalePressOptions {
  * ```
  */
 export declare function useScalePress(options?: ScalePressOptions): {
-    animatedStyle: {
+    animatedStyle: import("react-native-reanimated/lib/typescript/hook/commonTypes").AnimatedStyleHandle<{
         transform: {
             scale: number;
         }[];
-    };
+    }>;
     pressHandlers: {
         onPressIn: () => void;
         onPressOut: () => void;

package/dist/hooks/useStaggeredEntrance.d.ts

@@ -46,7 +46,7 @@ interface StaggeredEntranceOptions {
  * })}
  * ```
  */
-export declare function useStaggeredEntrance(options?: StaggeredEntranceOptions): {
+export declare function useStaggeredEntrance(options?: StaggeredEntranceOptions): import("react-native-reanimated/lib/typescript/hook/commonTypes").AnimatedStyleHandle<{
     opacity: number;
     transform?: undefined;
 } | {
@@ -59,7 +59,7 @@ export declare function useStaggeredEntrance(options?: StaggeredEntranceOptions)
     transform: {
         scale: number;
     }[];
-};
+}>;
 /**
  * Convenience constant: default stagger delay between items (ms)
  */

package/dist/state/themeStore.d.ts

@@ -11,3 +11,4 @@ export declare function resolveThemePreference(userTheme: ThemePreference, syste
 export declare const useThemeStore: import("zustand").UseBoundStore<import("zustand").StoreApi<ThemeStore>>;
 export declare function syncSystemTheme(): void;
 export declare function startSystemThemeListener(): () => void;
+export declare function syncThemeFromEnvironment(): () => void;

package/dist/state/themeStore.js

@@ -13,7 +13,9 @@ function getSystemTheme() {
 }
 export const useThemeStore = create((set) => ({
     userTheme: "system",
-    systemTheme: getSystemTheme(),
+    // Always start with "light" so SSR and the first client render agree.
+    // Real values are populated by `syncThemeFromEnvironment()` after mount.
+    systemTheme: "light",
     setTheme: (theme) => {
         set({
             userTheme: theme,
@@ -89,6 +91,18 @@ export function startSystemThemeListener() {
     };
     return stopSystemThemeListener;
 }
-// Load saved theme on store creation
-useThemeStore.getState().loadTheme();
-startSystemThemeListener();
+// Single entry point for host apps to populate the store from the
+// environment (persisted preference + OS color scheme listener). Safe to
+// call multiple times — `startSystemThemeListener` is idempotent — and
+// returns the unsubscribe so it can be used directly inside `useEffect`.
+export function syncThemeFromEnvironment() {
+    useThemeStore.getState().loadTheme();
+    return startSystemThemeListener();
+}
+// Native has no SSR mismatch concern, so keep the historical auto-init
+// behavior there. On web the host app must call `syncThemeFromEnvironment()`
+// from a top-level `useEffect` to avoid hydration mismatches.
+if (Platform.OS !== "web") {
+    useThemeStore.getState().loadTheme();
+    startSystemThemeListener();
+}

package/llms-full.md

@@ -36,6 +36,11 @@ the root when the app uses package feedback or overlay components.
 `BottomSheet`, `Drawer`, `DropdownMenu`, `Popover`, `SelectContent`,
 `Tooltip`, or `globalUIStore` notifications.
 
+On native, `BottomSheet.Content` composes its sheet transform with
+`react-native-keyboard-controller` keyboard animation values. Mount that
+library's `KeyboardProvider` near the app root before using bottom sheets with
+text inputs, or pass `avoidKeyboard={false}` for sheets that should not move.
+
 i18n is optional. Plain children and `text` props work without `i18next` or
 `react-i18next`. Use `configureExpoUiI18n()` only when a consuming app wants
 package `tx` props translated by its app-owned i18n instance.
@@ -82,7 +87,7 @@ Use this catalog before creating a new app-local primitive.
 | `Alert` | `@mrmeg/expo-ui/components` | Cross-platform imperative alerts | Avoid direct `window.alert` and duplicated native/web branching. |
 | `AnimatedView` | `@mrmeg/expo-ui/components` | Entrance and visibility animation | Keep simple reveal effects in the package wrapper. |
 | `Badge` | `@mrmeg/expo-ui/components` | Short status labels | Prefer over custom pill views. |
-| `BottomSheet` | `@mrmeg/expo-ui/components` | Mobile-first modal sheets | Requires root `UIProvider` portal setup. |
+| `BottomSheet` | `@mrmeg/expo-ui/components` | Mobile-first modal sheets | Requires root `UIProvider`; native text-input sheets also require `KeyboardProvider`. |
 | `Button` | `@mrmeg/expo-ui/components` | Commands and CTAs | Use `preset`, not `variant`; visible heights are compact. |
 | `Card` | `@mrmeg/expo-ui/components` | Individual framed content groups | Do not wrap whole page sections in cards. |
 | `Checkbox` | `@mrmeg/expo-ui/components` | Boolean selection in forms or lists | Prefer over custom checkmark controls. |

package/llms.txt

@@ -25,6 +25,8 @@ Call useResources() once near the Expo app root. Mount UIProvider once near the
 root before using package notifications or overlay primitives: Dialog,
 AlertDialog, BottomSheet, Drawer, DropdownMenu, Popover, SelectContent, or
 Tooltip.
+On native, mount react-native-keyboard-controller's KeyboardProvider before
+using BottomSheet.Content with text inputs; avoidKeyboard defaults to true.
 
 Use useTheme(), useStyles(), semantic tokens, StyledText, and package controls.
 Do not add app-local Appearance or matchMedia listeners for package theme sync.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrmeg/expo-ui",
-  "version": "0.1.10",
+  "version": "0.3.0",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [
@@ -12,7 +12,7 @@
     "universal-ui"
   ],
   "author": "Matt Megenhardt",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mrmeg/expo-template.git",
@@ -109,6 +109,7 @@
     "react": ">=19.2.0 <20.0.0",
     "react-native": ">=0.83.0 <0.84.0",
     "react-native-gesture-handler": "~2.30.0",
+    "react-native-keyboard-controller": ">=1.20.0 <2.0.0",
     "react-native-reanimated": "~4.2.0",
     "react-native-safe-area-context": "~5.6.0",
     "react-native-screens": "~4.23.0",
@@ -118,6 +119,6 @@
   },
   "devDependencies": {
     "@types/react": "~19.2.14",
-    "typescript": "~5.9.2"
+    "typescript": "~6.0.3"
   }
 }