@retray-dev/ui-kit 5.2.0 → 5.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retray-dev/ui-kit",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "Personal UI Kit for React Native / Expo",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -16,7 +16,8 @@
   "files": [
     "dist",
     "src",
-    "COMPONENTS.md"
+    "COMPONENTS.md",
+    "EXAMPLES.md"
   ],
   "scripts": {
     "build": "tsup",

package/src/components/Accordion/Accordion.tsx

@@ -17,11 +17,18 @@ import { Entypo } from '@expo/vector-icons'
 import { selectionAsync as hapticSelection } from '../../utils/haptics'
 import { useTheme } from '../../theme'
 import { s, vs, ms } from '../../utils/scaling'
+import { renderIcon } from '../../utils/icons'
 
 export interface AccordionItem {
   value: string
   trigger: string
   content: React.ReactNode
+  /** Icon name from @expo/vector-icons rendered left of trigger. */
+  iconName?: string
+  /** Custom icon node rendered left of trigger. */
+  icon?: React.ReactNode
+  /** Override icon color. Defaults to foregroundMuted. */
+  iconColor?: string
 }
 
 export interface AccordionProps {
@@ -47,6 +54,10 @@ function AccordionItemComponent({
 }) {
   const { colors } = useTheme()
 
+  const resolvedIcon = item.iconName
+    ? renderIcon(item.iconName, ms(16), item.iconColor ?? colors.foregroundMuted)
+    : item.icon
+
   // Shared values — all animation lives on the UI thread
   const isExpanded = useSharedValue(isOpen)
   const height = useSharedValue(0)
@@ -91,7 +102,10 @@ function AccordionItemComponent({
           onToggle()
         }}
       >
-        <Text style={[styles.triggerText, { color: colors.foreground }]} allowFontScaling={true}>{item.trigger}</Text>
+        <View style={styles.triggerContent}>
+          {resolvedIcon ? <View style={styles.icon}>{resolvedIcon}</View> : null}
+          <Text style={[styles.triggerText, { color: colors.foreground }]} allowFontScaling={true}>{item.trigger}</Text>
+        </View>
         <Animated.View style={[styles.chevron, rotationStyle]}>
           <Entypo name="chevron-down" size={18} color={colors.foregroundMuted} />
         </Animated.View>
@@ -163,10 +177,19 @@ const styles = StyleSheet.create({
     paddingHorizontal: s(14),
     paddingVertical: vs(12),
   },
+  triggerContent: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: s(8),
+    flex: 1,
+  },
+  icon: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
   triggerText: {
     fontFamily: 'Poppins-Medium',
     fontSize: ms(14),
-    flex: 1,
   },
   chevron: {
     marginLeft: s(8),

package/src/components/Avatar/Avatar.tsx

@@ -8,9 +8,12 @@ export type AvatarSize = 'sm' | 'md' | 'lg' | 'xl'
 export type AvatarStatus = 'online' | 'offline' | 'busy' | 'away'
 
 export interface AvatarProps {
-  src?: string
+  src?: string | null
+  /** Manual initials (max 2 chars). */
   fallback?: string
-  size?: AvatarSize
+  /** Full name — extracts up to 2 initials (e.g. "Julian Cruz" → "JC"). */
+  fallbackText?: string
+  size?: AvatarSize | number
   /** Optional status indicator dot — bottom-right corner. */
   status?: AvatarStatus
   style?: ViewStyle
@@ -37,13 +40,24 @@ const statusSizeMap: Record<AvatarSize, number> = {
   xl: 16,
 }
 
-export function Avatar({ src, fallback, size = 'md', status, style }: AvatarProps) {
+function getInitials(fallback?: string, fallbackText?: string): string {
+  if (fallback) return fallback.slice(0, 2).toUpperCase()
+  if (fallbackText) {
+    const words = fallbackText.trim().split(/\s+/)
+    if (words.length === 1) return words[0].slice(0, 2).toUpperCase()
+    return (words[0][0] + words[words.length - 1][0]).toUpperCase()
+  }
+  return '?'
+}
+
+export function Avatar({ src, fallback, fallbackText, size = 'md', status, style }: AvatarProps) {
   const { colors } = useTheme()
   const [imageError, setImageError] = useState(false)
-  const dimension = sizeMap[size]
+  const dimension = typeof size === 'number' ? size : sizeMap[size as AvatarSize]
+  const fontSize = typeof size === 'number' ? size * 0.38 : fontSizeMap[size as AvatarSize]
   const showFallback = !src || imageError
 
-  const statusSize = statusSizeMap[size]
+  const statusSize = typeof size === 'number' ? size * 0.25 : statusSizeMap[size as AvatarSize]
 
   const statusColor: Record<AvatarStatus, string> = {
     online:  '#22c55e',
@@ -71,10 +85,10 @@ export function Avatar({ src, fallback, size = 'md', status, style }: AvatarProp
           />
         ) : (
           <Text
-            style={[styles.fallback, { color: colors.foregroundMuted, fontSize: fontSizeMap[size] }]}
+            style={[styles.fallback, { color: colors.foregroundMuted, fontSize }]}
             allowFontScaling={true}
           >
-            {fallback?.slice(0, 2).toUpperCase() ?? '?'}
+            {getInitials(fallback, fallbackText)}
           </Text>
         )}
       </View>

package/src/components/Button/Button.tsx

@@ -14,7 +14,7 @@ import {
 const nativeDriver = Platform.OS !== 'web'
 import { impactLight } from '../../utils/haptics'
 import { useTheme } from '../../theme'
-import { s, vs, ms } from '../../utils/scaling'
+import { s, vs, ms, mvs } from '../../utils/scaling'
 import { renderIcon } from '../../utils/icons'
 import { RADIUS, TYPOGRAPHY } from '../../tokens'
 
@@ -31,7 +31,7 @@ export interface ButtonProps extends TouchableOpacityProps {
   size?: ButtonSize
   loading?: boolean
   fullWidth?: boolean
-  icon?: React.ReactNode | ((props: { label: string; size: ButtonSize; variant: ButtonVariant }) => React.ReactNode)
+  icon?: React.ReactNode | ((props: { label: string; size: ButtonSize; variant: ButtonVariant; color: string }) => React.ReactNode)
   iconName?: string
   iconColor?: string
   iconPosition?: 'left' | 'right'
@@ -47,7 +47,7 @@ const containerSizeStyles: Record<ButtonSize, ViewStyle> = {
 const labelSizeStyles: Record<ButtonSize, TextStyle> = {
   sm: { ...TYPOGRAPHY['button-sm'], fontSize: ms(TYPOGRAPHY['button-sm'].fontSize) },
   md: { ...TYPOGRAPHY['button-lg'], fontSize: ms(TYPOGRAPHY['button-lg'].fontSize) },
-  lg: { ...TYPOGRAPHY['button-lg'], fontSize: ms(TYPOGRAPHY['button-lg'].fontSize + 1) },
+  lg: { ...TYPOGRAPHY['button-lg'], fontSize: ms(TYPOGRAPHY['button-lg'].fontSize + 1), lineHeight: mvs(24) },
 }
 
 const iconSizeMap: Record<ButtonSize, number> = { sm: 16, md: 18, lg: 20 }
@@ -99,17 +99,24 @@ export function Button({
     destructive: { color: colors.destructiveForeground },
   }[variant]
 
+  const textColor = iconColor ?? (labelVariantStyle.color as string)
+
   const effectiveIcon: React.ReactNode = iconName
-    ? renderIcon(iconName, iconSizeMap[size], iconColor ?? (labelVariantStyle.color as string))
-    : typeof icon === 'function' ? icon({ label, size, variant }) : icon
+    ? renderIcon(iconName, iconSizeMap[size], textColor)
+    : typeof icon === 'function' ? icon({ label, size, variant, color: textColor }) : icon
 
   const spinnerColor =
     variant === 'destructive' ? colors.destructiveForeground
     : variant === 'primary' ? colors.primaryForeground
     : colors.foreground
 
+  // Extract flex from style for wrapper — ButtonGroup sets flex: 1
+  const styleArray = Array.isArray(style) ? style : style ? [style] : []
+  const flatStyle = StyleSheet.flatten(styleArray)
+  const { flex, ...restStyle } = flatStyle || {}
+
   return (
-    <Animated.View style={[fullWidth && styles.fullWidth, { transform: [{ scale }] }]}>
+    <Animated.View style={[fullWidth && styles.fullWidth, flex !== undefined && { flex }, { transform: [{ scale }] }]}>
       <TouchableOpacity
         style={[
           styles.base,
@@ -117,7 +124,7 @@ export function Button({
           containerSizeStyles[size],
           fullWidth && styles.fullWidth,
           isDisabled && styles.disabled,
-          style,
+          restStyle,
         ]}
         disabled={isDisabled}
         activeOpacity={1}
@@ -135,6 +142,7 @@ export function Button({
             <Text
               style={[styles.label, labelVariantStyle, labelSizeStyles[size], effectiveIcon ? styles.labelWithIcon : undefined]}
               allowFontScaling={true}
+              numberOfLines={1}
             >
               {label}
             </Text>
@@ -161,6 +169,7 @@ const styles = StyleSheet.create({
   },
   label: {
     fontFamily: 'Poppins-Medium',
+    flexShrink: 1,
   },
   labelWithIcon: {
     marginHorizontal: s(6),

package/src/components/ButtonGroup/ButtonGroup.tsx

@@ -0,0 +1,60 @@
+import React from 'react'
+import { View, ViewStyle, StyleSheet } from 'react-native'
+import { s } from '../../utils/scaling'
+
+export interface ButtonGroupProps {
+  children: React.ReactNode
+  /** Spacing between buttons. Defaults to 12px. */
+  gap?: number
+  /** Stack buttons vertically instead of horizontally. */
+  vertical?: boolean
+  style?: ViewStyle
+}
+
+/**
+ * Container that auto-distributes space equally among Button children.
+ * Each child gets `flex: 1` — perfect for side-by-side CTAs.
+ *
+ * @example
+ * ```tsx
+ * <ButtonGroup>
+ *   <Button label="Cancel" variant="secondary" onPress={...} />
+ *   <Button label="Confirm" onPress={...} />
+ * </ButtonGroup>
+ * ```
+ */
+export function ButtonGroup({ children, gap = 12, vertical = false, style }: ButtonGroupProps) {
+  return (
+    <View
+      style={[
+        styles.container,
+        vertical ? styles.vertical : styles.horizontal,
+        { gap: s(gap) },
+        style,
+      ]}
+    >
+      {React.Children.map(children, (child) =>
+        React.isValidElement(child)
+          ? React.cloneElement(child as React.ReactElement<any>, {
+              style: [
+                (child as React.ReactElement<any>).props.style,
+                { flex: 1 },
+              ],
+            })
+          : child,
+      )}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  container: {
+    width: '100%',
+  },
+  horizontal: {
+    flexDirection: 'row',
+  },
+  vertical: {
+    flexDirection: 'column',
+  },
+})

package/src/components/ButtonGroup/index.ts

@@ -0,0 +1 @@
+export * from './ButtonGroup'

package/src/components/Chip/Chip.tsx

@@ -30,6 +30,11 @@ export interface ChipProps {
 export interface ChipOption {
   label: string
   value: string | number
+  /** Icon name resolved via renderIcon (Feather, AntDesign, etc.). */
+  iconName?: string
+  /** Icon tint color override. */
+  iconColor?: string
+  disabled?: boolean
 }
 
 export interface ChipGroupProps {
@@ -154,7 +159,9 @@ export function ChipGroup({ options, value, onValueChange, multiSelect = false,
           key={opt.value}
           label={opt.label}
           selected={isSelected(opt.value)}
-          onPress={() => handlePress(opt.value)}
+          onPress={opt.disabled ? undefined : () => handlePress(opt.value)}
+          iconName={opt.iconName}
+          style={opt.disabled ? { opacity: 0.4 } : undefined}
         />
       ))}
     </View>

package/src/components/CurrencyDisplay/CurrencyDisplay.tsx

@@ -3,6 +3,15 @@ import { View, Text, StyleSheet, ViewStyle } from 'react-native'
 import { useTheme } from '../../theme'
 import { ms } from '../../utils/scaling'
 
+export type CurrencyDisplayVariant = 'hero' | 'large' | 'medium' | 'small'
+
+const variantFontSize: Record<CurrencyDisplayVariant, number> = {
+  hero:   ms(48),
+  large:  ms(32),
+  medium: ms(18),
+  small:  ms(14),
+}
+
 export interface CurrencyDisplayProps {
   value: number | string
   /** Symbol prepended to the formatted value. Defaults to `'$'`. */
@@ -11,6 +20,12 @@ export interface CurrencyDisplayProps {
   showDecimals?: boolean
   /** Override the color of the formatted text. Defaults to the `foreground` theme token. */
   textColor?: string
+  /** Predefined size variant. Overrides the default 56px size. */
+  variant?: CurrencyDisplayVariant
+  /** Enable adjustsFontSizeToFit so long values shrink to fit in one line. */
+  autoScale?: boolean
+  /** Maximum font size when autoScale is true (defaults to variant size or 56px). */
+  maxFontSize?: number
   style?: ViewStyle
 }
 
@@ -27,13 +42,21 @@ function formatValue(value: number | string, prefix: string, showDecimals: boole
   return `${sign}${prefix}${intPart}`
 }
 
-export function CurrencyDisplay({ value, prefix = '$', showDecimals = false, textColor, style }: CurrencyDisplayProps) {
+export function CurrencyDisplay({ value, prefix = '$', showDecimals = false, textColor, variant, autoScale, maxFontSize, style }: CurrencyDisplayProps) {
   const { colors } = useTheme()
   const formatted = formatValue(value, prefix, showDecimals)
+  const baseFontSize = variant ? variantFontSize[variant] : ms(56)
+  const fontSize = maxFontSize ?? baseFontSize
 
   return (
     <View style={[styles.container, style]}>
-      <Text style={[styles.amount, { color: textColor ?? colors.foreground }]} allowFontScaling={true}>
+      <Text
+        style={[styles.amount, { color: textColor ?? colors.foreground, fontSize }]}
+        allowFontScaling={true}
+        numberOfLines={autoScale ? 1 : undefined}
+        adjustsFontSizeToFit={autoScale}
+        minimumFontScale={autoScale ? 0.5 : undefined}
+      >
         {formatted}
       </Text>
     </View>
@@ -44,7 +67,6 @@ const styles = StyleSheet.create({
   container: {},
   amount: {
     fontFamily: 'Poppins-Bold',
-    fontSize: ms(56),
     letterSpacing: -2,
   },
 })

package/src/components/DetailRow/DetailRow.tsx

@@ -0,0 +1,140 @@
+import React from 'react'
+import { View, Text, StyleSheet, ViewStyle, TextStyle } from 'react-native'
+import { useTheme } from '../../theme'
+import { s, vs, ms, mvs } from '../../utils/scaling'
+import { renderIcon } from '../../utils/icons'
+
+export type DetailRowSeparator = 'dotted' | 'solid' | 'dashed' | 'none'
+export type DetailRowLabelWeight = 'normal' | 'medium' | 'semibold' | 'bold'
+
+const weightMap: Record<DetailRowLabelWeight, string> = {
+  normal:   'Poppins-Regular',
+  medium:   'Poppins-Medium',
+  semibold: 'Poppins-SemiBold',
+  bold:     'Poppins-Bold',
+}
+
+export interface DetailRowProps {
+  label: React.ReactNode
+  value: string
+  /** Dotted/dashed/solid line between label and value. Defaults to 'dotted'. */
+  separator?: DetailRowSeparator
+  labelWeight?: DetailRowLabelWeight
+  /** Semantic color key or hex string for value text. */
+  valueColor?: string
+  /** Node rendered left of the label (e.g. Avatar, Icon). */
+  leftIcon?: React.ReactNode
+  /** Icon name from @expo/vector-icons rendered left of label. Takes precedence over leftIcon. */
+  leftIconName?: string
+  /** Override left icon color. Defaults to foregroundMuted. */
+  leftIconColor?: string
+  /** Icon name from @expo/vector-icons rendered right of value. */
+  rightIconName?: string
+  /** Override right icon color. Defaults to foregroundMuted. */
+  rightIconColor?: string
+  style?: ViewStyle
+  labelStyle?: TextStyle
+  valueStyle?: TextStyle
+}
+
+export function DetailRow({
+  label,
+  value,
+  separator = 'dotted',
+  labelWeight = 'normal',
+  valueColor,
+  leftIcon,
+  leftIconName,
+  leftIconColor,
+  rightIconName,
+  rightIconColor,
+  style,
+  labelStyle,
+  valueStyle,
+}: DetailRowProps) {
+  const { colors } = useTheme()
+
+  const resolvedLeftIcon = leftIconName
+    ? renderIcon(leftIconName, ms(14), leftIconColor ?? colors.foregroundMuted)
+    : leftIcon
+
+  const resolvedRightIcon = rightIconName
+    ? renderIcon(rightIconName, ms(14), rightIconColor ?? colors.foregroundMuted)
+    : null
+
+  const separatorStyle: ViewStyle | null =
+    separator === 'none'
+      ? null
+      : {
+          flex: 1,
+          height: 1,
+          borderBottomWidth: 1,
+          borderStyle: separator,
+          borderColor: 'rgba(128,128,128,0.3)',
+          marginHorizontal: s(4),
+        }
+
+  return (
+    <View style={[styles.row, style]}>
+      <View style={styles.labelSide}>
+        {resolvedLeftIcon ? <View style={styles.icon}>{resolvedLeftIcon}</View> : null}
+        {typeof label === 'string' ? (
+          <Text
+            style={[styles.labelText, { color: colors.foregroundMuted, fontFamily: weightMap[labelWeight] }, labelStyle]}
+            allowFontScaling={true}
+          >
+            {label}
+          </Text>
+        ) : (
+          label
+        )}
+      </View>
+      {separatorStyle ? <View style={separatorStyle} /> : <View style={styles.spacer} />}
+      <View style={styles.valueSide}>
+        <Text
+          style={[styles.valueText, { color: valueColor ?? colors.foreground }, valueStyle]}
+          allowFontScaling={true}
+        >
+          {value}
+        </Text>
+        {resolvedRightIcon ? <View style={styles.icon}>{resolvedRightIcon}</View> : null}
+      </View>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: s(4),
+  },
+  labelSide: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: s(4),
+    flexShrink: 0,
+  },
+  icon: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  spacer: {
+    flex: 1,
+  },
+  labelText: {
+    fontSize: ms(13),
+    lineHeight: mvs(18),
+  },
+  valueSide: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: s(4),
+    flexShrink: 0,
+  },
+  valueText: {
+    fontFamily: 'Poppins-SemiBold',
+    fontSize: ms(13),
+    lineHeight: mvs(18),
+  },
+})

package/src/components/DetailRow/index.ts

@@ -0,0 +1 @@
+export * from './DetailRow'

package/src/components/LabelValue/LabelValue.tsx

@@ -2,21 +2,33 @@ import React from 'react'
 import { View, Text, StyleSheet, ViewStyle } from 'react-native'
 import { useTheme } from '../../theme'
 import { s, vs, ms, mvs } from '../../utils/scaling'
+import { renderIcon } from '../../utils/icons'
 
 export interface LabelValueProps {
   label: string
   value: string | React.ReactNode
+  /** Icon name from @expo/vector-icons rendered left of label. */
+  iconName?: string
+  /** Override icon color. Defaults to foregroundMuted. */
+  iconColor?: string
   style?: ViewStyle
 }
 
-export function LabelValue({ label, value, style }: LabelValueProps) {
+export function LabelValue({ label, value, iconName, iconColor, style }: LabelValueProps) {
   const { colors } = useTheme()
 
+  const resolvedIcon = iconName
+    ? renderIcon(iconName, ms(14), iconColor ?? colors.foregroundMuted)
+    : null
+
   return (
     <View style={[styles.container, style]}>
-      <Text style={[styles.label, { color: colors.foregroundMuted }]} allowFontScaling={true}>
-        {label}
-      </Text>
+      <View style={styles.labelSide}>
+        {resolvedIcon ? <View style={styles.icon}>{resolvedIcon}</View> : null}
+        <Text style={[styles.label, { color: colors.foregroundMuted }]} allowFontScaling={true}>
+          {label}
+        </Text>
+      </View>
       {typeof value === 'string' ? (
         <Text style={[styles.value, { color: colors.foreground }]} allowFontScaling={true}>
           {value}
@@ -35,6 +47,15 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     gap: s(12),
   },
+  labelSide: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: s(4),
+  },
+  icon: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
   label: {
     fontFamily: 'Poppins-Regular',
     fontSize: ms(13),

package/src/components/MonthPicker/MonthPicker.tsx

@@ -5,10 +5,12 @@ import { selectionAsync as hapticSelection } from '../../utils/haptics'
 import { useTheme } from '../../theme'
 import { s, vs, ms, mvs } from '../../utils/scaling'
 
-const MONTH_NAMES = [
-  'January', 'February', 'March', 'April', 'May', 'June',
-  'July', 'August', 'September', 'October', 'November', 'December',
-]
+const MONTH_NAMES: Record<string, string[]> = {
+  en: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
+  es: ['enero', 'febrero', 'marzo', 'abril', 'mayo', 'junio', 'julio', 'agosto', 'septiembre', 'octubre', 'noviembre', 'diciembre'],
+  pt: ['janeiro', 'fevereiro', 'março', 'abril', 'maio', 'junho', 'julho', 'agosto', 'setembro', 'outubro', 'novembro', 'dezembro'],
+  fr: ['janvier', 'février', 'mars', 'avril', 'mai', 'juin', 'juillet', 'août', 'septembre', 'octobre', 'novembre', 'décembre'],
+}
 
 export interface MonthPickerValue {
   /** Month number 1–12 */
@@ -19,12 +21,22 @@ export interface MonthPickerValue {
 export interface MonthPickerProps {
   value: MonthPickerValue
   onChange: (value: MonthPickerValue) => void
+  /** BCP 47 locale tag. Built-in: 'en' | 'es' | 'pt' | 'fr'. For other locales supply formatLabel. */
+  locale?: string
+  /** Custom label formatter. Takes precedence over locale. */
+  formatLabel?: (value: MonthPickerValue) => string
   style?: ViewStyle
 }
 
-export function MonthPicker({ value, onChange, style }: MonthPickerProps) {
+export function MonthPicker({ value, onChange, locale = 'en', formatLabel, style }: MonthPickerProps) {
   const { colors } = useTheme()
 
+  const getLabel = (): string => {
+    if (formatLabel) return formatLabel(value)
+    const names = MONTH_NAMES[locale] ?? MONTH_NAMES.en
+    return `${names[value.month - 1]} ${value.year}`
+  }
+
   const handlePrev = () => {
     hapticSelection()
     if (value.month === 1) {
@@ -54,7 +66,7 @@ export function MonthPicker({ value, onChange, style }: MonthPickerProps) {
         <Entypo name="chevron-left" size={22} color={colors.foreground} />
       </TouchableOpacity>
       <Text style={[styles.label, { color: colors.foreground }]} allowFontScaling={true}>
-        {MONTH_NAMES[value.month - 1]} {value.year}
+        {getLabel()}
       </Text>
       <TouchableOpacity
         style={styles.arrow}

package/src/components/Sheet/Sheet.tsx

@@ -1,5 +1,5 @@
 import React, { useEffect, useRef } from 'react'
-import { View, Text, StyleSheet, ViewStyle } from 'react-native'
+import { View, Text, StyleSheet, ViewStyle, KeyboardAvoidingView, Platform } from 'react-native'
 import {
   BottomSheetModal,
   BottomSheetView,
@@ -26,6 +26,10 @@ export interface SheetProps {
   scrollable?: boolean
   /** Cap sheet height (dp). Children scroll when content exceeds this value. */
   maxHeight?: number
+  /** Wrap content in KeyboardAvoidingView. Defaults to platform-appropriate behavior when set. */
+  keyboardBehavior?: 'padding' | 'height' | 'position' | 'none'
+  /** Extra vertical offset for the keyboard avoiding view. */
+  keyboardOffset?: number
 }
 
 export function Sheet({
@@ -37,6 +41,8 @@ export function Sheet({
   style,
   scrollable,
   maxHeight,
+  keyboardBehavior,
+  keyboardOffset = 0,
 }: SheetProps) {
   const { colors } = useTheme()
   const ref = useRef<BottomSheetModal>(null)
@@ -74,6 +80,16 @@ export function Sheet({
 
   const useScroll = scrollable || !!maxHeight
 
+  const wrapKeyboard = (node: React.ReactNode) => {
+    if (!keyboardBehavior || keyboardBehavior === 'none') return node
+    const behavior = keyboardBehavior ?? Platform.select({ ios: 'padding', android: 'height' }) as 'padding' | 'height'
+    return (
+      <KeyboardAvoidingView behavior={behavior} keyboardVerticalOffset={keyboardOffset}>
+        {node}
+      </KeyboardAvoidingView>
+    )
+  }
+
   return (
     <BottomSheetModal
       ref={ref}
@@ -85,7 +101,7 @@ export function Sheet({
       enablePanDownToClose
     >
       <BottomSheetView style={maxHeight ? { maxHeight } : undefined}>
-        {useScroll ? (
+        {wrapKeyboard(useScroll ? (
           <BottomSheetScrollView contentContainerStyle={[styles.content, style]}>
             {headerNode}
             {children}
@@ -95,7 +111,7 @@ export function Sheet({
             {headerNode}
             {children}
           </BottomSheetView>
-        )}
+        ))}
       </BottomSheetView>
     </BottomSheetModal>
   )