@mrmeg/expo-ui 0.6.1 → 0.7.0

package/LLM_USAGE.md

@@ -68,10 +68,9 @@ 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.
+On native, `BottomSheet.Content` avoids the soft keyboard by default with
+React Native keyboard events. 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`.
@@ -168,7 +167,7 @@ Use this table before creating a new app-local primitive.
 |-----------|---------|----------------------|--------------------------|
 | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` | Multi-section disclosure | Custom FAQ/settings expanders | FAQ lists, grouped settings, help sections |
 | `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 |
+| `AnimatedView` | Entrance and visibility animation | Hand-rolled one-off Animated 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, keyboard-aware quick edit forms |
 | `Button` | Commands and CTAs | Pressable plus custom text styling | Submit, save, cancel, delete, navigation CTAs |

package/README.md

@@ -29,12 +29,12 @@ bun add @mrmeg/expo-ui
 
 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.
+Native 0.83, and React Native Web 0.21. UI animations and keyboard-aware
+sheet offsets use React Native Animated by default.
 `@rn-primitives/*` packages are managed by `@mrmeg/expo-ui` because they are
 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
+keyboard avoidance uses React Native keyboard events. 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,
@@ -207,7 +207,7 @@ All components are exported from `@mrmeg/expo-ui/components`; direct imports suc
 |-----------|---------|----------------------|--------------------------|
 | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` | Multi-section disclosure | Custom FAQ/settings expanders | FAQ lists, grouped settings, help sections, dense detail pages |
 | `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 |
+| `AnimatedView` | Entrance and visibility animation | Hand-rolled one-off Animated 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, 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 |
@@ -272,7 +272,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, 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`.
+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 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/Accordion.js

@@ -1,10 +1,10 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
-import { Platform, Pressable, View } from "react-native";
-import Animated, { useSharedValue, useAnimatedStyle, withTiming, useReducedMotion, } from "react-native-reanimated";
+import { useEffect, useRef, useState } from "react";
+import { Animated, Platform, Pressable, View } from "react-native";
 import { Icon } from "./Icon.js";
-import { TextClassContext, TextSelectabilityContext } from "./StyledText.js";
+import { TextClassContext, TextSelectabilityContext } from "./StyledText.context";
 import { useTheme } from "../hooks/useTheme.js";
+import { useReducedMotion } from "../hooks/useReduceMotion.js";
 import { spacing } from "../constants/spacing.js";
 import * as AccordionPrimitive from "@rn-primitives/accordion";
 function normalizeSingleValue(value) {
@@ -100,20 +100,25 @@ function AccordionTrigger({ children, style: styleOverride, ...props }) {
     const { theme } = useTheme();
     const reduceMotion = useReducedMotion();
     const { isExpanded } = AccordionPrimitive.useItemContext();
-    const rotation = useSharedValue(isExpanded ? 1 : 0);
+    const rotation = useRef(new Animated.Value(isExpanded ? 1 : 0)).current;
     useEffect(() => {
         const target = isExpanded ? 1 : 0;
-        if (reduceMotion) {
-            rotation.value = target;
-            return;
-        }
-        rotation.value = withTiming(target, {
-            duration: isExpanded ? 200 : 150,
-        });
-    }, [isExpanded, reduceMotion]);
-    const chevronStyle = useAnimatedStyle(() => ({
-        transform: [{ rotate: `${rotation.value * 180}deg` }],
-    }));
+        Animated.timing(rotation, {
+            toValue: target,
+            duration: reduceMotion ? 0 : isExpanded ? 200 : 150,
+            useNativeDriver: true,
+        }).start();
+    }, [isExpanded, reduceMotion, rotation]);
+    const chevronStyle = {
+        transform: [
+            {
+                rotate: rotation.interpolate({
+                    inputRange: [0, 1],
+                    outputRange: ["0deg", "180deg"],
+                }),
+            },
+        ],
+    };
     return (_jsx(TextClassContext.Provider, { value: "", children: _jsx(TextSelectabilityContext.Provider, { value: false, children: _jsx(AccordionPrimitive.Header, { children: _jsx(AccordionPrimitive.Trigger, { ...props, asChild: true, children: _jsxs(Trigger, { style: [
                             {
                                 flexDirection: "row",

package/dist/components/AnimatedView.d.ts

@@ -25,7 +25,7 @@ interface AnimatedViewProps extends ViewProps {
 }
 /**
  * Cross-Platform Animated View Component
- * Uses Reanimated for smooth 60fps animations on all platforms
+ * Uses React Native Animated for lightweight cross-platform animations
  *
  * Features:
  * - Multiple animation types (fade, fadeSlideUp, fadeSlideDown, scale)

package/dist/components/AnimatedView.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import Animated from "react-native-reanimated";
+import { Animated } from "react-native";
 import { useStaggeredEntrance } from "../hooks/useStaggeredEntrance.js";
 /**
  * Cross-Platform Animated View Component
- * Uses Reanimated for smooth 60fps animations on all platforms
+ * Uses React Native Animated for lightweight cross-platform animations
  *
  * Features:
  * - Multiple animation types (fade, fadeSlideUp, fadeSlideDown, scale)

package/dist/components/Badge.d.ts

@@ -2,7 +2,8 @@ import React from "react";
 import { StyleProp, ViewStyle } from "react-native";
 export type BadgeVariant = "default" | "secondary" | "outline" | "destructive";
 export interface BadgeProps {
-    children: React.ReactNode;
+    children?: React.ReactNode;
+    text?: string;
     variant?: BadgeVariant;
     style?: StyleProp<ViewStyle>;
 }
@@ -19,5 +20,5 @@ export interface BadgeProps {
  * <Badge variant="destructive">Error</Badge>
  * ```
  */
-declare function Badge({ children, variant, style: styleOverride }: BadgeProps): import("react/jsx-runtime").JSX.Element;
+declare function Badge({ children, text, variant, style: styleOverride }: BadgeProps): import("react/jsx-runtime").JSX.Element;
 export { Badge };

package/dist/components/Badge.js

@@ -17,9 +17,10 @@ import { StyledText } from "./StyledText.js";
  * <Badge variant="destructive">Error</Badge>
  * ```
  */
-function Badge({ children, variant = "default", style: styleOverride }) {
+function Badge({ children, text, variant = "default", style: styleOverride }) {
     const { theme } = useTheme();
     const styles = useMemo(() => createStyles(theme), [theme]);
+    const badgeContent = text ?? children;
     const textStyle = [
         styles.text,
         variant === "default" && { color: theme.colors.primaryForeground },
@@ -27,9 +28,9 @@ function Badge({ children, variant = "default", style: styleOverride }) {
         variant === "outline" && { color: theme.colors.foreground },
         variant === "destructive" && { color: theme.colors.destructiveForeground },
     ];
-    const normalizedChildren = React.Children.toArray(children);
+    const normalizedChildren = React.Children.toArray(badgeContent);
     const hasOnlyTextChildren = normalizedChildren.every((child) => typeof child === "string" || typeof child === "number");
-    const content = hasOnlyTextChildren ? (_jsx(StyledText, { selectable: false, style: textStyle, children: normalizedChildren.join("") })) : (React.Children.map(children, (child) => {
+    const content = hasOnlyTextChildren ? (_jsx(StyledText, { selectable: false, style: textStyle, children: normalizedChildren.join("") })) : (React.Children.map(badgeContent, (child) => {
         if (typeof child === "string" || typeof child === "number") {
             return _jsx(StyledText, { selectable: false, style: textStyle, children: child });
         }

package/dist/components/BottomSheet.js

@@ -1,15 +1,16 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-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 React, { createContext, use, useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
+import { View, Pressable, Animated, StyleSheet, Platform, 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 { useDimensions } from "../hooks/useDimensions.js";
 import { spacing } from "../constants/spacing.js";
 import { shouldUseNativeDriver } from "../lib/animations.js";
-import { TextColorContext, TextClassContext } from "./StyledText.js";
+import { TextColorContext, TextClassContext } from "./StyledText.context";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { BottomSheetKeyboardController, useBottomSheetKeyboardAnimation, } from "./BottomSheetKeyboard.js";
 /**
  * BottomSheet Component with Sub-components
  *
@@ -44,7 +45,7 @@ const FullWindowOverlay = Platform.OS === "ios" ? RNFullWindowOverlay : React.Fr
 // ============================================================================
 const BottomSheetContext = createContext(null);
 function useBottomSheetContext() {
-    const context = useContext(BottomSheetContext);
+    const context = use(BottomSheetContext);
     if (!context) {
         throw new Error("BottomSheet components must be used within a BottomSheet");
     }
@@ -61,15 +62,14 @@ function BottomSheetPanel({ accessibilityViewIsModal, children, panHandlers, she
         ], accessibilityViewIsModal: accessibilityViewIsModal, ...panHandlers, ...props, children: children }));
 }
 function KeyboardAvoidingBottomSheetPanel(props) {
-    const { height: keyboardHeight } = useKeyboardAnimation();
+    const { height: keyboardHeight } = useBottomSheetKeyboardAnimation();
     const composedTranslateY = useMemo(() => Animated.add(props.translateY, keyboardHeight), [keyboardHeight, props.translateY]);
     return _jsx(BottomSheetPanel, { ...props, translateY: composedTranslateY });
 }
 // ============================================================================
 // Utility Functions
 // ============================================================================
-function resolveSnapPoints(points) {
-    const screenHeight = Dimensions.get("window").height;
+function resolveSnapPoints(points, screenHeight) {
     return points.map((p) => {
         if (typeof p === "number")
             return p;
@@ -90,7 +90,9 @@ function BottomSheetRoot({ open: controlledOpen, onOpenChange: controlledOnOpenC
     const [internalOpen, dispatch] = useReducer(sheetReducer, defaultOpen);
     const isControlled = controlledOpen !== undefined;
     const open = isControlled ? controlledOpen : internalOpen;
-    const snapPoints = resolveSnapPoints(rawSnapPoints);
+    // useDimensions reacts to rotation / split-screen, unlike Dimensions.get.
+    const { height: screenHeight } = useDimensions();
+    const snapPoints = resolveSnapPoints(rawSnapPoints, screenHeight);
     const toggle = () => {
         if (isControlled) {
             controlledOnOpenChange?.(!controlledOpen);
@@ -149,8 +151,18 @@ function BottomSheetContent({ swipeEnabled = true, velocityThreshold = 500, avoi
     const maxHeight = Math.max(...snapPoints);
     // With bottom:0 positioning, translateY=0 means visible, translateY=maxHeight means hidden below
     const closedPosition = maxHeight;
-    const translateY = useRef(new Animated.Value(open ? 0 : closedPosition)).current;
-    const backdropOpacity = useRef(new Animated.Value(open ? 1 : 0)).current;
+    // Initialize lazily so each Animated.Value is allocated once on first render
+    // instead of being rebuilt and discarded on every render.
+    const translateYRef = useRef(null);
+    if (translateYRef.current === null) {
+        translateYRef.current = new Animated.Value(open ? 0 : closedPosition);
+    }
+    const translateY = translateYRef.current;
+    const backdropOpacityRef = useRef(null);
+    if (backdropOpacityRef.current === null) {
+        backdropOpacityRef.current = new Animated.Value(open ? 1 : 0);
+    }
+    const backdropOpacity = backdropOpacityRef.current;
     const [isVisible, setIsVisible] = useState(open);
     const lastOpenRef = useRef(null);
     const runningAnimationRef = useRef(null);
@@ -158,9 +170,6 @@ function BottomSheetContent({ swipeEnabled = true, velocityThreshold = 500, avoi
     // Track which snap we're at
     const currentSnapRef = useRef(snapPoints.length - 1);
     const textColor = theme.colors.foreground;
-    // ------------------------------------------------------------------
-    // Shared snap/close logic used by both native PanResponder and web drag
-    // ------------------------------------------------------------------
     const handleDragRelease = useCallback((dragDistance, velocity) => {
         const visibleHeight = currentHeightRef.current - dragDistance;
         if (velocity > velocityThreshold / 1000 || dragDistance > currentHeightRef.current * 0.4) {
@@ -241,12 +250,9 @@ function BottomSheetContent({ swipeEnabled = true, velocityThreshold = 500, avoi
     }, [translateY, backdropOpacity, maxHeight]);
     const dismissKeyboardForDrag = useCallback(() => {
         if (Platform.OS !== "web" && dismissKeyboardOnDrag) {
-            void KeyboardController.dismiss();
+            void BottomSheetKeyboardController.dismiss();
         }
     }, [dismissKeyboardOnDrag]);
-    // ------------------------------------------------------------------
-    // Trigger animation during render if open changed
-    // ------------------------------------------------------------------
     if (open !== lastOpenRef.current) {
         const previousOpen = lastOpenRef.current;
         lastOpenRef.current = open;
@@ -304,9 +310,6 @@ function BottomSheetContent({ swipeEnabled = true, velocityThreshold = 500, avoi
             });
         }
     }
-    // ------------------------------------------------------------------
-    // Native: PanResponder for swipe gestures on the whole sheet
-    // ------------------------------------------------------------------
     const panResponder = useMemo(() => Platform.OS !== "web" && swipeEnabled
         ? PanResponder.create({
             onStartShouldSetPanResponder: () => false,
@@ -325,9 +328,6 @@ function BottomSheetContent({ swipeEnabled = true, velocityThreshold = 500, avoi
             },
         })
         : null, [dismissKeyboardForDrag, handleDragMove, handleDragRelease, swipeEnabled]);
-    // ------------------------------------------------------------------
-    // Web: drag context provides callbacks for Handle's pointer events
-    // ------------------------------------------------------------------
     const dragContextValue = Platform.OS === "web" && swipeEnabled
         ? {
             onDragMove: handleDragMove,
@@ -363,25 +363,27 @@ function BottomSheetContent({ swipeEnabled = true, velocityThreshold = 500, avoi
     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: [
+    return (_jsx(BottomSheetContentPortal, { sheetContext: sheetContext, theme: theme, backdropOpacity: backdropOpacity, onBackdropPress: handleBackdropPress, PanelComponent: PanelComponent, sheetStyle: sheetStyle, styleOverride: styleOverride, translateY: translateY, panHandlers: panResponder ? panResponder.panHandlers : undefined, panelProps: props, dragContextValue: dragContextValue, sheetContent: sheetContent }));
+}
+function BottomSheetContentPortal({ sheetContext, theme, backdropOpacity, onBackdropPress, PanelComponent, sheetStyle, styleOverride, translateY, panHandlers, panelProps, dragContextValue, sheetContent, }) {
+    return (_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,
                                 {
                                     backgroundColor: theme.colors.overlay,
                                     opacity: backdropOpacity,
                                 },
                                 Platform.OS === "web" && { zIndex: 50 },
-                            ], children: _jsx(Pressable, { style: StyleSheet.absoluteFill, onPress: handleBackdropPress }) }), _jsx(PanelComponent, { sheetStyle: sheetStyle, styleOverride: styleOverride, translateY: translateY, accessibilityViewIsModal: true, ...(Platform.OS === "web" && {
+                            ], children: _jsx(Pressable, { style: StyleSheet.absoluteFill, onPress: onBackdropPress }) }), _jsx(PanelComponent, { sheetStyle: sheetStyle, styleOverride: styleOverride, translateY: translateY, accessibilityViewIsModal: true, ...(Platform.OS === "web" && {
                                 role: "dialog",
                                 "aria-modal": true,
-                            }), panHandlers: panResponder ? panResponder.panHandlers : undefined, ...props, children: dragContextValue ? (_jsx(DragContext.Provider, { value: dragContextValue, children: sheetContent })) : (sheetContent) })] }) }) }) }));
-    return contentElement;
+                            }), panHandlers: panHandlers, ...panelProps, children: dragContextValue ? (_jsx(DragContext.Provider, { value: dragContextValue, children: sheetContent })) : (sheetContent) })] }) }) }) }));
 }
 // ============================================================================
 // Handle
 // ============================================================================
 function BottomSheetHandle({ style }) {
     const { theme } = useTheme();
-    const dragCtx = useContext(DragContext);
+    const dragCtx = use(DragContext);
     // Web pointer-event drag — attaches move/up listeners on document
     const dragStartY = useRef(0);
     const lastTimestamp = useRef(0);

package/dist/components/BottomSheetKeyboard.d.ts

@@ -0,0 +1,7 @@
+import { Animated } from "react-native";
+export declare function useBottomSheetKeyboardAnimation(): {
+    height: Animated.Value;
+};
+export declare const BottomSheetKeyboardController: {
+    dismiss(): void;
+};

package/dist/components/BottomSheetKeyboard.js

@@ -0,0 +1,35 @@
+import { useEffect, useRef } from "react";
+import { Animated, Keyboard, Platform } from "react-native";
+function animateKeyboardOffset(value, toValue, duration = 180) {
+    Animated.timing(value, {
+        toValue,
+        duration,
+        useNativeDriver: true,
+    }).start();
+}
+export function useBottomSheetKeyboardAnimation() {
+    const keyboardHeight = useRef(new Animated.Value(0)).current;
+    useEffect(() => {
+        if (Platform.OS === "web") {
+            return;
+        }
+        const showEvent = Platform.OS === "ios" ? "keyboardWillShow" : "keyboardDidShow";
+        const hideEvent = Platform.OS === "ios" ? "keyboardWillHide" : "keyboardDidHide";
+        const showSubscription = Keyboard.addListener(showEvent, (event) => {
+            animateKeyboardOffset(keyboardHeight, -event.endCoordinates.height, event.duration || 180);
+        });
+        const hideSubscription = Keyboard.addListener(hideEvent, (event) => {
+            animateKeyboardOffset(keyboardHeight, 0, event.duration || 160);
+        });
+        return () => {
+            showSubscription.remove();
+            hideSubscription.remove();
+        };
+    }, [keyboardHeight]);
+    return { height: keyboardHeight };
+}
+export const BottomSheetKeyboardController = {
+    dismiss() {
+        Keyboard.dismiss();
+    },
+};

package/dist/components/Button.d.ts

@@ -1,6 +1,7 @@
 import React, { ComponentType } from "react";
 import { PressableProps, PressableStateCallbackType, DimensionValue, StyleProp, TextStyle, ViewStyle } from "react-native";
 import { TextProps } from "./StyledText";
+import { type IconProps } from "./Icon";
 /**
  * Button variants
  */
@@ -115,26 +116,67 @@ export interface ButtonProps extends PressableProps {
  *
  * Usage:
  * ```tsx
- * // Default button
- * <Button onPress={handler}>
- *   <SansSerifBoldText>Click Me</SansSerifBoldText>
- * </Button>
+ * // Simplest path — plain label via the `text` prop
+ * <Button onPress={handler} text="Click Me" />
  *
  * // Different variants
- * <Button preset="outline" onPress={handler}>Outline</Button>
- * <Button preset="ghost" onPress={handler}>Ghost</Button>
- * <Button preset="destructive" onPress={handler}>Delete</Button>
+ * <Button preset="outline" onPress={handler} text="Outline" />
+ * <Button preset="ghost" onPress={handler} text="Ghost" />
+ * <Button preset="destructive" onPress={handler} text="Delete" />
  *
  * // Different sizes
- * <Button size="sm" onPress={handler}>Small</Button>
- * <Button size="lg" onPress={handler}>Large</Button>
+ * <Button size="sm" onPress={handler} text="Small" />
+ * <Button size="lg" onPress={handler} text="Large" />
  *
  * // Loading state
- * <Button loading onPress={handler}>Processing...</Button>
+ * <Button loading onPress={handler} text="Processing..." />
  *
  * // Full width
- * <Button fullWidth onPress={handler}>Submit</Button>
+ * <Button fullWidth onPress={handler} text="Submit" />
+ *
+ * // Composed content — icon + label via subcomponents
+ * <Button onPress={handler}>
+ *   <Button.Icon name="heart" />
+ *   <Button.Text>Like</Button.Text>
+ * </Button>
+ * ```
+ */
+declare function ButtonRoot(props: ButtonProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Button.Text
+ * Text content for a Button. Inherits the button's control typography, color,
+ * and non-selectable behavior from context, so callers state their intent
+ * explicitly instead of relying on the component to inspect `typeof children`.
+ *
+ * ```tsx
+ * <Button onPress={save}>
+ *   <Button.Text>Save</Button.Text>
+ * </Button>
  * ```
  */
-export declare function Button(props: ButtonProps): import("react/jsx-runtime").JSX.Element;
-export {};
+declare function ButtonText(props: TextProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Button.Icon
+ * Icon content for a Button. Defaults its color to the button's text color
+ * (from context) and is decorative by default, since the label conveys meaning.
+ *
+ * ```tsx
+ * <Button onPress={like}>
+ *   <Button.Icon name="heart" />
+ *   <Button.Text>Like</Button.Text>
+ * </Button>
+ * ```
+ */
+declare function ButtonIcon(props: IconProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Button with explicit subcomponents.
+ * - `Button.Text` for label text (inherits control typography)
+ * - `Button.Icon` for icons (inherits the button's text color)
+ *
+ * The `tx`/`text` props remain the simplest path for plain labels.
+ */
+declare const Button: typeof ButtonRoot & {
+    Text: typeof ButtonText;
+    Icon: typeof ButtonIcon;
+};
+export { Button, ButtonText, ButtonIcon };

package/dist/components/Button.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useMemo, useState } from "react";
-import { Pressable, StyleSheet, View, Platform, ActivityIndicator, } from "react-native";
-import Animated from "react-native-reanimated";
+import { use, useCallback, useMemo, useState } from "react";
+import { Pressable, StyleSheet, View, Platform, ActivityIndicator, Animated, } from "react-native";
 import { spacing } from "../constants/spacing.js";
-import { StyledText, TextColorContext, TextSelectabilityContext, TextStyleContext } from "./StyledText.js";
+import { StyledText } from "./StyledText.js";
+import { Icon } from "./Icon.js";
+import { TextColorContext, TextSelectabilityContext, TextStyleContext } from "./StyledText.context";
 import { fontFamilies } from "../constants/fonts.js";
 import { palette } from "../constants/colors.js";
 import { useTheme } from "../hooks/useTheme.js";
@@ -43,28 +44,32 @@ const getNativeHitSlop = (sizeConfig) => Math.ceil(Math.max(0, spacing.touchTarg
  *
  * Usage:
  * ```tsx
- * // Default button
- * <Button onPress={handler}>
- *   <SansSerifBoldText>Click Me</SansSerifBoldText>
- * </Button>
+ * // Simplest path — plain label via the `text` prop
+ * <Button onPress={handler} text="Click Me" />
  *
  * // Different variants
- * <Button preset="outline" onPress={handler}>Outline</Button>
- * <Button preset="ghost" onPress={handler}>Ghost</Button>
- * <Button preset="destructive" onPress={handler}>Delete</Button>
+ * <Button preset="outline" onPress={handler} text="Outline" />
+ * <Button preset="ghost" onPress={handler} text="Ghost" />
+ * <Button preset="destructive" onPress={handler} text="Delete" />
  *
  * // Different sizes
- * <Button size="sm" onPress={handler}>Small</Button>
- * <Button size="lg" onPress={handler}>Large</Button>
+ * <Button size="sm" onPress={handler} text="Small" />
+ * <Button size="lg" onPress={handler} text="Large" />
  *
  * // Loading state
- * <Button loading onPress={handler}>Processing...</Button>
+ * <Button loading onPress={handler} text="Processing..." />
  *
  * // Full width
- * <Button fullWidth onPress={handler}>Submit</Button>
+ * <Button fullWidth onPress={handler} text="Submit" />
+ *
+ * // Composed content — icon + label via subcomponents
+ * <Button onPress={handler}>
+ *   <Button.Icon name="heart" />
+ *   <Button.Text>Like</Button.Text>
+ * </Button>
  * ```
  */
-export function Button(props) {
+function ButtonRoot(props) {
     const { tx, text, txOptions, style: styleOverride, pressedStyle: pressedStyleOverride, textStyle: textStyleOverride, pressedTextStyle: pressedTextStyleOverride, disabledTextStyle: disabledTextStyleOverride, children, RightAccessory, LeftAccessory, disabled, disabledStyle: disabledStyleOverride, withShadow = false, preset = "default", size = "md", loading = false, fullWidth = false, onFocus, onBlur, onPressIn, onPressOut, ...rest } = props;
     const { theme, getContrastingColor, getFocusRingStyle, getShadowStyle } = useTheme();
     const styles = useMemo(() => createStyles(theme, size), [theme, size]);
@@ -115,11 +120,11 @@ export function Button(props) {
         haptic: false,
         scaleTo: preset === "link" ? 1 : 0.97,
     });
-    const handleFocus = (event) => {
+    const showFocusRing = (event) => {
         setFocused(true);
         onFocus?.(event);
     };
-    const handleBlur = (event) => {
+    const hideFocusRing = (event) => {
         setFocused(false);
         onBlur?.(event);
     };
@@ -144,7 +149,7 @@ export function Button(props) {
             return nextWidth;
         });
     }, [fullWidth, loading]);
-    return (_jsx(TextColorContext.Provider, { value: textColor, children: _jsx(TextSelectabilityContext.Provider, { value: false, children: _jsx(TextStyleContext.Provider, { value: styles.text, children: _jsx(Pressable, { accessibilityRole: "button", accessibilityState: { disabled: !!isDisabled, busy: loading }, ...rest, onPressIn: handlePressIn, onPressOut: handlePressOut, onFocus: handleFocus, onBlur: handleBlur, style: { alignSelf: fullWidth ? "stretch" : flattenedStyle?.alignSelf ?? "flex-start" }, hitSlop: rest.hitSlop ?? (Platform.OS === "web" ? undefined : getNativeHitSlop(sizeConfig)), disabled: isDisabled, children: (state) => (_jsx(Animated.View, { style: scaleStyle, children: _jsxs(View, { style: [
+    return (_jsx(TextColorContext.Provider, { value: textColor, children: _jsx(TextSelectabilityContext.Provider, { value: false, children: _jsx(TextStyleContext.Provider, { value: styles.text, children: _jsx(Pressable, { accessibilityRole: "button", accessibilityState: { disabled: !!isDisabled, busy: loading }, ...rest, onPressIn: handlePressIn, onPressOut: handlePressOut, onFocus: showFocusRing, onBlur: hideFocusRing, style: { alignSelf: fullWidth ? "stretch" : flattenedStyle?.alignSelf ?? "flex-start" }, hitSlop: rest.hitSlop ?? (Platform.OS === "web" ? undefined : getNativeHitSlop(sizeConfig)), disabled: isDisabled, children: (state) => (_jsx(Animated.View, { style: scaleStyle, children: _jsxs(View, { style: [
                                 styles.button,
                                 preset === "default" && styles.buttonDefault,
                                 preset === "outline" && styles.buttonOutline,
@@ -170,15 +175,42 @@ export function Button(props) {
                                                 state.pressed && pressedTextStyleOverride,
                                                 isDisabled && disabledTextStyleOverride,
                                                 textStyleOverride,
-                                            ] })) : children ? (
-                                        // Wrap string children in StyledText to apply control typography.
-                                        typeof children === "string" ? (_jsx(StyledText, { style: [
-                                                styles.text,
-                                                state.pressed && styles.pressedText,
-                                                state.pressed && pressedTextStyleOverride,
-                                                isDisabled && disabledTextStyleOverride,
-                                                textStyleOverride,
-                                            ], children: children })) : (children)) : (null), !!RightAccessory && (_jsx(RightAccessory, { style: styles.rightAccessory, pressableState: state, disabled: isDisabled }))] })] }) })) }) }) }) }));
+                                            ] })) : (
+                                        // Children render as-is. For text content, use the explicit
+                                        // <Button.Text> subcomponent so it inherits control typography
+                                        // via context instead of relying on a runtime `typeof` check.
+                                        children ?? null), !!RightAccessory && (_jsx(RightAccessory, { style: styles.rightAccessory, pressableState: state, disabled: isDisabled }))] })] }) })) }) }) }) }));
+}
+/**
+ * Button.Text
+ * Text content for a Button. Inherits the button's control typography, color,
+ * and non-selectable behavior from context, so callers state their intent
+ * explicitly instead of relying on the component to inspect `typeof children`.
+ *
+ * ```tsx
+ * <Button onPress={save}>
+ *   <Button.Text>Save</Button.Text>
+ * </Button>
+ * ```
+ */
+function ButtonText(props) {
+    return _jsx(StyledText, { ...props });
+}
+/**
+ * Button.Icon
+ * Icon content for a Button. Defaults its color to the button's text color
+ * (from context) and is decorative by default, since the label conveys meaning.
+ *
+ * ```tsx
+ * <Button onPress={like}>
+ *   <Button.Icon name="heart" />
+ *   <Button.Text>Like</Button.Text>
+ * </Button>
+ * ```
+ */
+function ButtonIcon(props) {
+    const contextColor = use(TextColorContext);
+    return _jsx(Icon, { decorative: true, color: contextColor, ...props });
 }
 const createStyles = (theme, size) => {
     const sizeConfig = SIZE_CONFIGS[size];
@@ -263,3 +295,15 @@ const createStyles = (theme, size) => {
         },
     });
 };
+/**
+ * Button with explicit subcomponents.
+ * - `Button.Text` for label text (inherits control typography)
+ * - `Button.Icon` for icons (inherits the button's text color)
+ *
+ * The `tx`/`text` props remain the simplest path for plain labels.
+ */
+const Button = Object.assign(ButtonRoot, {
+    Text: ButtonText,
+    Icon: ButtonIcon,
+});
+export { Button, ButtonText, ButtonIcon };