@retray-dev/ui-kit 5.1.0 → 5.4.0

package/README.md

@@ -2,8 +2,8 @@
 
 A personal React Native / Expo UI component library with a built-in design system, dark mode support, haptic feedback, and smooth animations.
 
-- 36 components across 7 categories
-- Light/dark theme with 23 color tokens and full customization
+- 37 components across 7 categories
+- Light/dark theme with 12 public tokens (24 resolved) and full customization
 - Apple HIG–compliant touch targets and haptic feedback
 - Animated interactions: spring press, sliding tabs, accordion easing, animated progress
 - Built with TypeScript — full type declarations included
@@ -113,25 +113,28 @@ import { useTheme } from '@retray-dev/ui-kit'
 const { colors, colorScheme } = useTheme()
 ```
 
-**Available tokens:** `background`, `foreground`, `card`, `cardForeground`, `primary`, `primaryForeground`, `secondary`, `secondaryForeground`, `muted`, `mutedForeground`, `accent`, `accentForeground`, `destructive`, `destructiveForeground`, `destructiveTint`, `destructiveBorder`, `border`, `input`, `ring`, `success`, `successForeground`, `successTint`, `successBorder`
+**Public tokens (12 — override these):** `background`, `foreground`, `card`, `primary`, `primaryForeground`, `border`, `destructive`, `destructiveForeground`, `success`, `successForeground`, `warning`, `warningForeground`
+
+**Derived tokens (read-only via `useTheme()`):** `foregroundSubtle`, `foregroundMuted`, `surface`, `surfaceStrong`, `destructiveTint`, `destructiveBorder`, `successTint`, `successBorder`, `warningTint`, `warningBorder`, `ring`, `input`
 
 ## Design Tokens
 
 Static structural constants — no provider required:
 
 ```ts
-import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS } from '@retray-dev/ui-kit'
+import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS, TYPOGRAPHY } from '@retray-dev/ui-kit'
 
-<View style={{ gap: SPACING.md, padding: SPACING.lg, borderRadius: RADIUS.lg, ...SHADOWS.sm }} />
+<View style={{ gap: SPACING.md, padding: SPACING.base, borderRadius: RADIUS.md, ...SHADOWS.sm }} />
 ```
 
 | Token | Keys |
 |-------|------|
-| `SPACING` | `xs` (4), `sm` (8), `md` (12), `lg` (16), `xl` (24), `2xl` (32), `3xl` (48) |
+| `SPACING` | `xxs` (2), `xs` (4), `sm` (8), `md` (12), `base` (16), `lg` (24), `xl` (32), `xxl` (48), `section` (64) |
 | `ICON_SIZES` | `sm` (14), `md` (18), `lg` (22), `xl` (28), `2xl` (32) |
-| `RADIUS` | `sm` (4), `md` (8), `lg` (12), `xl` (16), `full` (9999) |
+| `RADIUS` | `none` (0), `xs` (4), `sm` (8), `md` (14), `lg` (20), `xl` (32), `full` (9999) |
 | `SHADOWS` | `sm`, `md`, `lg`, `xl` — cross-platform shadow presets |
 | `BREAKPOINTS` | `wide` (700) |
+| `TYPOGRAPHY` | 16 variants: `display-hero`, `display-xl`, `display-lg`, `display-md`, `display-sm`, `title-md`, `title-sm`, `body-md`, `body-sm`, `caption`, `caption-sm`, `badge-text`, `micro-label`, `uppercase-tag`, `button-lg`, `button-sm` |
 
 ## Components
 
@@ -139,11 +142,11 @@ import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS } from '@retray-dev/u
 | ----------- | ----------------------------------------------------------------------------------------------- |
 | Display     | `Text`, `Badge`, `Avatar`, `Separator`, `Spinner`, `Skeleton`, `Progress`, `CurrencyDisplay`   |
 | Surfaces    | `Card`, `AlertBanner`, `EmptyState`, `MediaCard`                                                |
-| Form        | `Button`, `IconButton`, `Input`, `CurrencyInput`, `CurrencyInputLarge`, `Textarea`, `Checkbox`, `Switch`, `Toggle`, `RadioGroup`, `Select`, `Slider` |
+| Form        | `Button`, `ButtonGroup`, `IconButton`, `Input`, `CurrencyInput`, `Textarea`, `Checkbox`, `Switch`, `Toggle`, `RadioGroup`, `Select`, `Slider` |
 | Composition | `Tabs`, `Accordion`                                                                             |
 | Overlays    | `Sheet`, `ConfirmDialog`                                                                        |
 | Feedback    | `Toast` / `ToastProvider` / `useToast`                                                          |
-| Data        | `ListItem`, `Chip` / `ChipGroup`, `LabelValue`, `MonthPicker`, `CategoryStrip`                 |
+| Data        | `ListItem`, `Chip` / `ChipGroup`, `LabelValue`, `MonthPicker`, `CategoryStrip`, `DetailRow`    |
 | Utilities   | `Pressable`                                                                                     |
 
 ### Quick examples

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { TouchableOpacityProps, TextProps as TextProps$1, TextInputProps, TextStyle, ViewStyle, ActivityIndicatorProps, ImageSourcePropType } from 'react-native';
+import { TouchableOpacityProps, ViewStyle, TextProps as TextProps$1, TextInputProps, TextStyle, ActivityIndicatorProps, ImageSourcePropType } from 'react-native';
 export { BottomSheetModalProvider } from '@gorhom/bottom-sheet';
 
 type ThemeColors = {
@@ -74,6 +74,7 @@ interface ButtonProps extends TouchableOpacityProps {
         label: string;
         size: ButtonSize;
         variant: ButtonVariant;
+        color: string;
     }) => React.ReactNode);
     iconName?: string;
     iconColor?: string;
@@ -81,6 +82,28 @@ interface ButtonProps extends TouchableOpacityProps {
 }
 declare function Button({ label, variant, size, loading, fullWidth, icon, iconName, iconColor, iconPosition, disabled, style, onPress, ...props }: ButtonProps): React.JSX.Element;
 
+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>
+ * ```
+ */
+declare function ButtonGroup({ children, gap, vertical, style }: ButtonGroupProps): React.JSX.Element;
+
 type IconButtonVariant = 'primary' | 'secondary' | 'outline' | 'text' | 'destructive';
 type IconButtonSize = 'sm' | 'md' | 'lg';
 interface IconButtonProps extends TouchableOpacityProps {
@@ -229,14 +252,17 @@ declare function Skeleton({ width, height, borderRadius, preset, diameter, style
 type AvatarSize = 'sm' | 'md' | 'lg' | 'xl';
 type AvatarStatus = 'online' | 'offline' | 'busy' | 'away';
 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;
 }
-declare function Avatar({ src, fallback, size, status, style }: AvatarProps): React.JSX.Element;
+declare function Avatar({ src, fallback, fallbackText, size, status, style }: AvatarProps): React.JSX.Element;
 
 type AlertBannerVariant = 'default' | 'destructive' | 'success' | 'warning';
 interface AlertBannerProps {
@@ -285,10 +311,16 @@ interface TextareaProps extends TextInputProps {
     hint?: string;
     /** Number of visible text rows. Defaults to `4`. Controls `numberOfLines` and `minHeight`. */
     rows?: number;
+    /** Icon name from @expo/vector-icons rendered inside top-left corner. */
+    prefixIcon?: string;
+    /** Custom icon node rendered top-left. */
+    prefixIconNode?: React.ReactNode;
+    /** Override prefix icon color. Defaults to foregroundMuted. */
+    prefixIconColor?: string;
     /** Style for the outer container `View`. Use `style` (from `TextInputProps`) to style the `TextInput` itself. */
     containerStyle?: ViewStyle;
 }
-declare function Textarea({ label, error, hint, rows, containerStyle, style, onFocus, onBlur, ...props }: TextareaProps): React.JSX.Element;
+declare function Textarea({ label, error, hint, rows, prefixIcon, prefixIconNode, prefixIconColor, containerStyle, style, onFocus, onBlur, ...props }: TextareaProps): React.JSX.Element;
 
 interface CheckboxProps {
     checked?: boolean;
@@ -377,6 +409,12 @@ 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;
 }
 interface AccordionProps {
     items: AccordionItem[];
@@ -413,10 +451,18 @@ interface SheetProps {
     title?: string;
     description?: string;
     children?: React.ReactNode;
-    /** Style for the inner `BottomSheetView` content container. */
+    /** Style for the inner content container. */
     style?: ViewStyle;
+    /** Render children inside BottomSheetScrollView so gestures are handled correctly on both platforms. */
+    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;
 }
-declare function Sheet({ open, onClose, title, description, children, style, }: SheetProps): React.JSX.Element;
+declare function Sheet({ open, onClose, title, description, children, style, scrollable, maxHeight, keyboardBehavior, keyboardOffset, }: SheetProps): React.JSX.Element;
 
 interface SelectOption {
     label: string;
@@ -490,6 +536,7 @@ interface CurrencyInputProps {
 }
 declare function CurrencyInput({ value, onChangeText, onChangeValue, prefix, thousandsSeparator, size, label, error, hint, placeholder, editable, containerStyle, style, }: CurrencyInputProps): React.JSX.Element;
 
+type CurrencyDisplayVariant = 'hero' | 'large' | 'medium' | 'small';
 interface CurrencyDisplayProps {
     value: number | string;
     /** Symbol prepended to the formatted value. Defaults to `'$'`. */
@@ -498,9 +545,15 @@ 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;
 }
-declare function CurrencyDisplay({ value, prefix, showDecimals, textColor, style }: CurrencyDisplayProps): React.JSX.Element;
+declare function CurrencyDisplay({ value, prefix, showDecimals, textColor, variant, autoScale, maxFontSize, style }: CurrencyDisplayProps): React.JSX.Element;
 
 type ListItemVariant = 'plain' | 'card';
 interface ListItemProps {
@@ -572,6 +625,11 @@ interface ChipProps {
 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;
 }
 interface ChipGroupProps {
     options: ChipOption[];
@@ -599,9 +657,13 @@ declare function ConfirmDialog({ visible, title, description, confirmLabel, canc
 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;
 }
-declare function LabelValue({ label, value, style }: LabelValueProps): React.JSX.Element;
+declare function LabelValue({ label, value, iconName, iconColor, style }: LabelValueProps): React.JSX.Element;
 
 interface MonthPickerValue {
     /** Month number 1–12 */
@@ -611,9 +673,13 @@ interface MonthPickerValue {
 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;
 }
-declare function MonthPicker({ value, onChange, style }: MonthPickerProps): React.JSX.Element;
+declare function MonthPicker({ value, onChange, locale, formatLabel, style }: MonthPickerProps): React.JSX.Element;
 
 type MediaCardAspectRatio = '1:1' | '4:3' | '16:9' | '4:5' | '3:2';
 interface MediaCardProps {
@@ -692,6 +758,32 @@ interface PressableProps extends Omit<TouchableOpacityProps, 'activeOpacity'> {
  */
 declare function Pressable({ children, onPress, pressScale, bounciness, haptics, style, disabled, hoverScale, ...touchableProps }: PressableProps): React.JSX.Element;
 
+type DetailRowSeparator = 'dotted' | 'solid' | 'dashed' | 'none';
+type DetailRowLabelWeight = 'normal' | 'medium' | 'semibold' | 'bold';
+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;
+}
+declare function DetailRow({ label, value, separator, labelWeight, valueColor, leftIcon, leftIconName, leftIconColor, rightIconName, rightIconColor, style, labelStyle, valueStyle, }: DetailRowProps): React.JSX.Element;
+
 type IconFamily = 'Feather' | 'AntDesign' | 'Entypo' | 'FontAwesome5' | 'MaterialIcons' | 'Ionicons';
 interface IconProps {
     /** Icon name from any supported @expo/vector-icons family. See https://icons.expo.fyi */
@@ -704,6 +796,19 @@ interface IconProps {
 declare function Icon({ name, size, color, family }: IconProps): React.ReactElement | null;
 declare function renderIcon(name: string, size: number, color: string): React.ReactElement | null;
 
+/**
+ * Returns a font size that steps down as formatted text grows longer.
+ * Designed for currency/numeric displays where long values overflow.
+ *
+ * @param text - The formatted string (e.g. "$1.250.000")
+ * @param maxSize - Base (maximum) font size in points
+ * @param steps - Custom step config [{ maxLen, subtract }] — sorted ascending by maxLen
+ */
+declare function getResponsiveFontSize(text: string, maxSize: number, steps?: {
+    maxLen: number;
+    subtract: number;
+}[]): number;
+
 declare const SPACING: {
     readonly xxs: 2;
     readonly xs: 4;
@@ -880,7 +985,7 @@ declare const TYPOGRAPHY: {
         readonly fontFamily: "Poppins-Medium";
         readonly fontSize: 16;
         readonly fontWeight: "500";
-        readonly lineHeight: 20;
+        readonly lineHeight: 22;
         readonly letterSpacing: 0;
     };
     readonly 'button-sm': {
@@ -900,4 +1005,4 @@ type RadiusKey = keyof Radius;
 type Typography = typeof TYPOGRAPHY;
 type TypographyKey = keyof Typography;
 
-export { Accordion, type AccordionItem, type AccordionProps, AlertBanner, type AlertBannerProps, type AlertBannerVariant, Avatar, type AvatarProps, type AvatarSize, BREAKPOINTS, Badge, type BadgeProps, type BadgeVariant, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Card, CardContent, type CardContentProps, CardDescription, type CardDescriptionProps, CardFooter, type CardFooterProps, CardHeader, type CardHeaderProps, type CardProps, CardTitle, type CardTitleProps, type CategoryItem, CategoryStrip, type CategoryStripProps, Checkbox, type CheckboxProps, Chip, ChipGroup, type ChipGroupProps, type ChipOption, type ChipProps, type ColorScheme, ConfirmDialog, type ConfirmDialogProps, CurrencyDisplay, type CurrencyDisplayProps, CurrencyInput, CurrencyInput as CurrencyInputLarge, type CurrencyInputProps, EmptyState, type EmptyStateProps, ICON_SIZES, Icon, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, type IconFamily, type IconProps, type IconSize, type IconSizeKey, Input, type InputProps, LabelValue, type LabelValueProps, ListItem, type ListItemProps, MediaCard, type MediaCardAspectRatio, type MediaCardProps, MonthPicker, type MonthPickerProps, type MonthPickerValue, Pressable, type PressableProps, Progress, type ProgressProps, RADIUS, RadioGroup, type RadioGroupProps, type RadioOption, type Radius, type RadiusKey, type ResolvedColors, SHADOWS, SPACING, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetProps, Skeleton, type SkeletonProps, Slider, type SliderProps, type Spacing, type SpacingKey, Spinner, type SpinnerProps, type SpinnerSize, Switch, type SwitchProps, TYPOGRAPHY, type TabItem, Tabs, TabsContent, type TabsContentProps, type TabsProps, Text, type TextProps, type TextVariant, Textarea, type TextareaProps, type Theme, type ThemeColors, ThemeProvider, type ThemeProviderProps, type ToastItem, ToastProvider, type ToastProviderProps, type ToastVariant, Toggle, type ToggleProps, type ToggleSize, type ToggleVariant, type Typography, type TypographyKey, defaultDark, defaultLight, deriveColors, renderIcon, useTheme, useToast };
+export { Accordion, type AccordionItem, type AccordionProps, AlertBanner, type AlertBannerProps, type AlertBannerVariant, Avatar, type AvatarProps, type AvatarSize, BREAKPOINTS, Badge, type BadgeProps, type BadgeVariant, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, type ButtonSize, type ButtonVariant, Card, CardContent, type CardContentProps, CardDescription, type CardDescriptionProps, CardFooter, type CardFooterProps, CardHeader, type CardHeaderProps, type CardProps, CardTitle, type CardTitleProps, type CategoryItem, CategoryStrip, type CategoryStripProps, Checkbox, type CheckboxProps, Chip, ChipGroup, type ChipGroupProps, type ChipOption, type ChipProps, type ColorScheme, ConfirmDialog, type ConfirmDialogProps, CurrencyDisplay, type CurrencyDisplayProps, type CurrencyDisplayVariant, CurrencyInput, CurrencyInput as CurrencyInputLarge, type CurrencyInputProps, DetailRow, type DetailRowLabelWeight, type DetailRowProps, type DetailRowSeparator, EmptyState, type EmptyStateProps, ICON_SIZES, Icon, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, type IconFamily, type IconProps, type IconSize, type IconSizeKey, Input, type InputProps, LabelValue, type LabelValueProps, ListItem, type ListItemProps, MediaCard, type MediaCardAspectRatio, type MediaCardProps, MonthPicker, type MonthPickerProps, type MonthPickerValue, Pressable, type PressableProps, Progress, type ProgressProps, RADIUS, RadioGroup, type RadioGroupProps, type RadioOption, type Radius, type RadiusKey, type ResolvedColors, SHADOWS, SPACING, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetProps, Skeleton, type SkeletonProps, Slider, type SliderProps, type Spacing, type SpacingKey, Spinner, type SpinnerProps, type SpinnerSize, Switch, type SwitchProps, TYPOGRAPHY, type TabItem, Tabs, TabsContent, type TabsContentProps, type TabsProps, Text, type TextProps, type TextVariant, Textarea, type TextareaProps, type Theme, type ThemeColors, ThemeProvider, type ThemeProviderProps, type ToastItem, ToastProvider, type ToastProviderProps, type ToastVariant, Toggle, type ToggleProps, type ToggleSize, type ToggleVariant, type Typography, type TypographyKey, defaultDark, defaultLight, deriveColors, getResponsiveFontSize, renderIcon, useTheme, useToast };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { TouchableOpacityProps, TextProps as TextProps$1, TextInputProps, TextStyle, ViewStyle, ActivityIndicatorProps, ImageSourcePropType } from 'react-native';
+import { TouchableOpacityProps, ViewStyle, TextProps as TextProps$1, TextInputProps, TextStyle, ActivityIndicatorProps, ImageSourcePropType } from 'react-native';
 export { BottomSheetModalProvider } from '@gorhom/bottom-sheet';
 
 type ThemeColors = {
@@ -74,6 +74,7 @@ interface ButtonProps extends TouchableOpacityProps {
         label: string;
         size: ButtonSize;
         variant: ButtonVariant;
+        color: string;
     }) => React.ReactNode);
     iconName?: string;
     iconColor?: string;
@@ -81,6 +82,28 @@ interface ButtonProps extends TouchableOpacityProps {
 }
 declare function Button({ label, variant, size, loading, fullWidth, icon, iconName, iconColor, iconPosition, disabled, style, onPress, ...props }: ButtonProps): React.JSX.Element;
 
+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>
+ * ```
+ */
+declare function ButtonGroup({ children, gap, vertical, style }: ButtonGroupProps): React.JSX.Element;
+
 type IconButtonVariant = 'primary' | 'secondary' | 'outline' | 'text' | 'destructive';
 type IconButtonSize = 'sm' | 'md' | 'lg';
 interface IconButtonProps extends TouchableOpacityProps {
@@ -229,14 +252,17 @@ declare function Skeleton({ width, height, borderRadius, preset, diameter, style
 type AvatarSize = 'sm' | 'md' | 'lg' | 'xl';
 type AvatarStatus = 'online' | 'offline' | 'busy' | 'away';
 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;
 }
-declare function Avatar({ src, fallback, size, status, style }: AvatarProps): React.JSX.Element;
+declare function Avatar({ src, fallback, fallbackText, size, status, style }: AvatarProps): React.JSX.Element;
 
 type AlertBannerVariant = 'default' | 'destructive' | 'success' | 'warning';
 interface AlertBannerProps {
@@ -285,10 +311,16 @@ interface TextareaProps extends TextInputProps {
     hint?: string;
     /** Number of visible text rows. Defaults to `4`. Controls `numberOfLines` and `minHeight`. */
     rows?: number;
+    /** Icon name from @expo/vector-icons rendered inside top-left corner. */
+    prefixIcon?: string;
+    /** Custom icon node rendered top-left. */
+    prefixIconNode?: React.ReactNode;
+    /** Override prefix icon color. Defaults to foregroundMuted. */
+    prefixIconColor?: string;
     /** Style for the outer container `View`. Use `style` (from `TextInputProps`) to style the `TextInput` itself. */
     containerStyle?: ViewStyle;
 }
-declare function Textarea({ label, error, hint, rows, containerStyle, style, onFocus, onBlur, ...props }: TextareaProps): React.JSX.Element;
+declare function Textarea({ label, error, hint, rows, prefixIcon, prefixIconNode, prefixIconColor, containerStyle, style, onFocus, onBlur, ...props }: TextareaProps): React.JSX.Element;
 
 interface CheckboxProps {
     checked?: boolean;
@@ -377,6 +409,12 @@ 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;
 }
 interface AccordionProps {
     items: AccordionItem[];
@@ -413,10 +451,18 @@ interface SheetProps {
     title?: string;
     description?: string;
     children?: React.ReactNode;
-    /** Style for the inner `BottomSheetView` content container. */
+    /** Style for the inner content container. */
     style?: ViewStyle;
+    /** Render children inside BottomSheetScrollView so gestures are handled correctly on both platforms. */
+    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;
 }
-declare function Sheet({ open, onClose, title, description, children, style, }: SheetProps): React.JSX.Element;
+declare function Sheet({ open, onClose, title, description, children, style, scrollable, maxHeight, keyboardBehavior, keyboardOffset, }: SheetProps): React.JSX.Element;
 
 interface SelectOption {
     label: string;
@@ -490,6 +536,7 @@ interface CurrencyInputProps {
 }
 declare function CurrencyInput({ value, onChangeText, onChangeValue, prefix, thousandsSeparator, size, label, error, hint, placeholder, editable, containerStyle, style, }: CurrencyInputProps): React.JSX.Element;
 
+type CurrencyDisplayVariant = 'hero' | 'large' | 'medium' | 'small';
 interface CurrencyDisplayProps {
     value: number | string;
     /** Symbol prepended to the formatted value. Defaults to `'$'`. */
@@ -498,9 +545,15 @@ 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;
 }
-declare function CurrencyDisplay({ value, prefix, showDecimals, textColor, style }: CurrencyDisplayProps): React.JSX.Element;
+declare function CurrencyDisplay({ value, prefix, showDecimals, textColor, variant, autoScale, maxFontSize, style }: CurrencyDisplayProps): React.JSX.Element;
 
 type ListItemVariant = 'plain' | 'card';
 interface ListItemProps {
@@ -572,6 +625,11 @@ interface ChipProps {
 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;
 }
 interface ChipGroupProps {
     options: ChipOption[];
@@ -599,9 +657,13 @@ declare function ConfirmDialog({ visible, title, description, confirmLabel, canc
 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;
 }
-declare function LabelValue({ label, value, style }: LabelValueProps): React.JSX.Element;
+declare function LabelValue({ label, value, iconName, iconColor, style }: LabelValueProps): React.JSX.Element;
 
 interface MonthPickerValue {
     /** Month number 1–12 */
@@ -611,9 +673,13 @@ interface MonthPickerValue {
 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;
 }
-declare function MonthPicker({ value, onChange, style }: MonthPickerProps): React.JSX.Element;
+declare function MonthPicker({ value, onChange, locale, formatLabel, style }: MonthPickerProps): React.JSX.Element;
 
 type MediaCardAspectRatio = '1:1' | '4:3' | '16:9' | '4:5' | '3:2';
 interface MediaCardProps {
@@ -692,6 +758,32 @@ interface PressableProps extends Omit<TouchableOpacityProps, 'activeOpacity'> {
  */
 declare function Pressable({ children, onPress, pressScale, bounciness, haptics, style, disabled, hoverScale, ...touchableProps }: PressableProps): React.JSX.Element;
 
+type DetailRowSeparator = 'dotted' | 'solid' | 'dashed' | 'none';
+type DetailRowLabelWeight = 'normal' | 'medium' | 'semibold' | 'bold';
+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;
+}
+declare function DetailRow({ label, value, separator, labelWeight, valueColor, leftIcon, leftIconName, leftIconColor, rightIconName, rightIconColor, style, labelStyle, valueStyle, }: DetailRowProps): React.JSX.Element;
+
 type IconFamily = 'Feather' | 'AntDesign' | 'Entypo' | 'FontAwesome5' | 'MaterialIcons' | 'Ionicons';
 interface IconProps {
     /** Icon name from any supported @expo/vector-icons family. See https://icons.expo.fyi */
@@ -704,6 +796,19 @@ interface IconProps {
 declare function Icon({ name, size, color, family }: IconProps): React.ReactElement | null;
 declare function renderIcon(name: string, size: number, color: string): React.ReactElement | null;
 
+/**
+ * Returns a font size that steps down as formatted text grows longer.
+ * Designed for currency/numeric displays where long values overflow.
+ *
+ * @param text - The formatted string (e.g. "$1.250.000")
+ * @param maxSize - Base (maximum) font size in points
+ * @param steps - Custom step config [{ maxLen, subtract }] — sorted ascending by maxLen
+ */
+declare function getResponsiveFontSize(text: string, maxSize: number, steps?: {
+    maxLen: number;
+    subtract: number;
+}[]): number;
+
 declare const SPACING: {
     readonly xxs: 2;
     readonly xs: 4;
@@ -880,7 +985,7 @@ declare const TYPOGRAPHY: {
         readonly fontFamily: "Poppins-Medium";
         readonly fontSize: 16;
         readonly fontWeight: "500";
-        readonly lineHeight: 20;
+        readonly lineHeight: 22;
         readonly letterSpacing: 0;
     };
     readonly 'button-sm': {
@@ -900,4 +1005,4 @@ type RadiusKey = keyof Radius;
 type Typography = typeof TYPOGRAPHY;
 type TypographyKey = keyof Typography;
 
-export { Accordion, type AccordionItem, type AccordionProps, AlertBanner, type AlertBannerProps, type AlertBannerVariant, Avatar, type AvatarProps, type AvatarSize, BREAKPOINTS, Badge, type BadgeProps, type BadgeVariant, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Card, CardContent, type CardContentProps, CardDescription, type CardDescriptionProps, CardFooter, type CardFooterProps, CardHeader, type CardHeaderProps, type CardProps, CardTitle, type CardTitleProps, type CategoryItem, CategoryStrip, type CategoryStripProps, Checkbox, type CheckboxProps, Chip, ChipGroup, type ChipGroupProps, type ChipOption, type ChipProps, type ColorScheme, ConfirmDialog, type ConfirmDialogProps, CurrencyDisplay, type CurrencyDisplayProps, CurrencyInput, CurrencyInput as CurrencyInputLarge, type CurrencyInputProps, EmptyState, type EmptyStateProps, ICON_SIZES, Icon, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, type IconFamily, type IconProps, type IconSize, type IconSizeKey, Input, type InputProps, LabelValue, type LabelValueProps, ListItem, type ListItemProps, MediaCard, type MediaCardAspectRatio, type MediaCardProps, MonthPicker, type MonthPickerProps, type MonthPickerValue, Pressable, type PressableProps, Progress, type ProgressProps, RADIUS, RadioGroup, type RadioGroupProps, type RadioOption, type Radius, type RadiusKey, type ResolvedColors, SHADOWS, SPACING, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetProps, Skeleton, type SkeletonProps, Slider, type SliderProps, type Spacing, type SpacingKey, Spinner, type SpinnerProps, type SpinnerSize, Switch, type SwitchProps, TYPOGRAPHY, type TabItem, Tabs, TabsContent, type TabsContentProps, type TabsProps, Text, type TextProps, type TextVariant, Textarea, type TextareaProps, type Theme, type ThemeColors, ThemeProvider, type ThemeProviderProps, type ToastItem, ToastProvider, type ToastProviderProps, type ToastVariant, Toggle, type ToggleProps, type ToggleSize, type ToggleVariant, type Typography, type TypographyKey, defaultDark, defaultLight, deriveColors, renderIcon, useTheme, useToast };
+export { Accordion, type AccordionItem, type AccordionProps, AlertBanner, type AlertBannerProps, type AlertBannerVariant, Avatar, type AvatarProps, type AvatarSize, BREAKPOINTS, Badge, type BadgeProps, type BadgeVariant, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, type ButtonSize, type ButtonVariant, Card, CardContent, type CardContentProps, CardDescription, type CardDescriptionProps, CardFooter, type CardFooterProps, CardHeader, type CardHeaderProps, type CardProps, CardTitle, type CardTitleProps, type CategoryItem, CategoryStrip, type CategoryStripProps, Checkbox, type CheckboxProps, Chip, ChipGroup, type ChipGroupProps, type ChipOption, type ChipProps, type ColorScheme, ConfirmDialog, type ConfirmDialogProps, CurrencyDisplay, type CurrencyDisplayProps, type CurrencyDisplayVariant, CurrencyInput, CurrencyInput as CurrencyInputLarge, type CurrencyInputProps, DetailRow, type DetailRowLabelWeight, type DetailRowProps, type DetailRowSeparator, EmptyState, type EmptyStateProps, ICON_SIZES, Icon, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, type IconFamily, type IconProps, type IconSize, type IconSizeKey, Input, type InputProps, LabelValue, type LabelValueProps, ListItem, type ListItemProps, MediaCard, type MediaCardAspectRatio, type MediaCardProps, MonthPicker, type MonthPickerProps, type MonthPickerValue, Pressable, type PressableProps, Progress, type ProgressProps, RADIUS, RadioGroup, type RadioGroupProps, type RadioOption, type Radius, type RadiusKey, type ResolvedColors, SHADOWS, SPACING, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetProps, Skeleton, type SkeletonProps, Slider, type SliderProps, type Spacing, type SpacingKey, Spinner, type SpinnerProps, type SpinnerSize, Switch, type SwitchProps, TYPOGRAPHY, type TabItem, Tabs, TabsContent, type TabsContentProps, type TabsProps, Text, type TextProps, type TextVariant, Textarea, type TextareaProps, type Theme, type ThemeColors, ThemeProvider, type ThemeProviderProps, type ToastItem, ToastProvider, type ToastProviderProps, type ToastVariant, Toggle, type ToggleProps, type ToggleSize, type ToggleVariant, type Typography, type TypographyKey, defaultDark, defaultLight, deriveColors, getResponsiveFontSize, renderIcon, useTheme, useToast };