@retray-dev/ui-kit 5.2.0 → 6.0.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v5.2.0)
+# @retray-dev/ui-kit — Component Reference (v6.0.0)
 
 This file is the AI reference for this package. It is shipped inside the npm package so consuming projects can import it into their `CLAUDE.md` with:
 
@@ -36,11 +36,11 @@ export default function App() {
 ```
 
 **Provider order is mandatory:**
-- `SafeAreaProvider` must be outermost — required by `useSafeAreaInsets` in `ToastProvider`
+- `SafeAreaProvider` must be outermost — required by `@gorhom/bottom-sheet`
 - `initialMetrics={initialWindowMetrics}` is required on Android to avoid a "No safe area value available" crash on first render
 - `GestureHandlerRootView` must wrap everything — required by `@gorhom/bottom-sheet`
 - `BottomSheetModalProvider` must be inside `GestureHandlerRootView`
-- `ToastProvider` must be inside `SafeAreaProvider`
+- `ToastProvider` wraps children and renders `Toaster` (from `sonner-native`) internally
 
 ## Typography — Poppins (Required)
 
@@ -136,6 +136,9 @@ These are the only values you need to supply when customizing the theme. The lib
 | `successForeground` | `#ffffff` | `#ffffff` | Text/icon on success backgrounds |
 | `warning` | `#e67e00` | `#f57c00` | Warning / caution states |
 | `warningForeground` | `#ffffff` | `#ffffff` | Text/icon on warning backgrounds |
+| `overlay` *(optional)* | `rgba(0,0,0,0.45)` | `rgba(0,0,0,0.45)` | Backdrop/overlay color behind sheets and dialogs |
+| `accent` *(optional)* | same as `primary` | same as `primary` | Secondary brand accent (e.g. Airbnb coral). Falls back to `primary` |
+| `accentForeground` *(optional)* | same as `primaryForeground` | same as `primaryForeground` | Text/icon on accent backgrounds. Falls back to `primaryForeground` |
 
 ### Derived Tokens (ResolvedColors) — read-only via useTheme().colors
 
@@ -155,6 +158,9 @@ The full palette components consume. Never supply these directly — they are co
 | `warningBorder` | `warning` @ 30% | Warning banner border |
 | `ring` | `= primary` | Focus ring color (always matches primary) |
 | `input` | `= border` | Input field border (always matches border) |
+| `overlay` | `overlay` token or `rgba(0,0,0,0.45)` | Backdrop behind sheets and dialogs |
+| `accentResolved` | `accent` token or `= primary` | Resolved accent color — always present |
+| `accentForegroundResolved` | `accentForeground` token or `= primaryForeground` | Resolved text on accent — always present |
 
 **Usage example — building a custom component using derived tokens:**
 ```tsx
@@ -231,10 +237,10 @@ import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS, TYPOGRAPHY } from '@
 | `none` | 0 | No rounding |
 | `xs` | 4 | Micro chips, tags |
 | `sm` | 8 | Inputs, Textarea, Select, Checkbox |
-| `md` | 14 | Cards, MediaCard, AlertBanner, Toast, EmptyState |
+| `md` | 14 | Cards, Buttons (all variants), MediaCard, AlertBanner, Toast, EmptyState |
 | `lg` | 20 | Sheet top corners |
-| `xl` | 32 | Primary CTA buttons (pill-like) |
-| `full` | 9999 | Circular elements, CategoryStrip chips |
+| `xl` | 32 | Large decorative elements |
+| `full` | 9999 | IconButton (circle), CategoryStrip chips |
 
 **Types:** `Radius`, `RadiusKey`
 
@@ -286,7 +292,7 @@ All components use these tokens for text styling. Import and use in custom compo
 | `caption-sm` | 13 | 400 | 16 | 0 | Timestamps, metadata |
 | `badge-text` | 11 | 600 | 13 | 0 | Badge labels, small tags |
 | `micro-label` | 12 | 700 | 16 | 0 | Micro labels, overlines |
-| `uppercase-tag` | 8 | 700 | 10 | 0.32 | Uppercase decorative tags (auto-uppercase) |
+| `uppercase-tag` | 10 | 700 | 13 | 0.8 | Uppercase decorative tags (auto-uppercase) |
 | `button-lg` | 16 | 500 | 20 | 0 | Button labels (md/lg size) |
 | `button-sm` | 14 | 500 | 18 | 0 | Button labels (sm size) |
 
@@ -344,6 +350,59 @@ const styles = StyleSheet.create({
 
 ---
 
+## Migration Guide: v5 → v6
+
+### New Components
+
+**`MenuItem`** — Navigation row with icon, label, and optional right slot (`rightRender`). Replaces ad-hoc `ListItem` usage for settings/nav menus. Zero horizontal padding by design — consumer controls spacing.
+
+```tsx
+import { MenuItem } from '@retray-dev/ui-kit'
+// variants: 'plain' (default) | 'card'
+<MenuItem label="Profile" iconName="user" onPress={() => {}} />
+<MenuItem label="Notifications" iconName="bell" rightRender={<Switch value={on} onValueChange={setOn} />} showChevron={false} onPress={() => {}} />
+```
+
+### Breaking Changes
+
+**Sheet keyboard defaults changed:**
+| Prop | v5 default | v6 default |
+|------|-----------|-----------|
+| `keyboardBehavior` | `'fillParent'` (Android) / `'interactive'` (iOS) | `'interactive'` (both) |
+| `android_keyboardInputMode` | `'adjustResize'` | `'adjustPan'` |
+
+If you relied on `adjustResize`, set it explicitly: `android_keyboardInputMode="adjustResize"`.
+
+**Toast API simplified:**
+
+```tsx
+// v5 — hook-only API
+const { toast } = useToast()
+toast.success('Done')
+
+// v6 — direct import preferred (hook still works for compat)
+import { toast } from '@retray-dev/ui-kit'
+toast.success('Done')
+```
+
+### New Theme Tokens
+
+Three optional `ThemeColors` tokens — fall back gracefully if omitted:
+
+| Token | Default | Purpose |
+|-------|---------|---------|
+| `overlay` | `rgba(0,0,0,0.45)` | Backdrop color behind sheets and dialogs |
+| `accent` | `= primary` | Secondary brand accent color |
+| `accentForeground` | `= primaryForeground` | Text on accent backgrounds |
+
+Access resolved values via `useTheme().colors.overlay`, `.accentResolved`, `.accentForegroundResolved`.
+
+### Token Corrections
+
+- `TYPOGRAPHY['uppercase-tag']` — size corrected to `10` (was documented as `8`, actual value was always `10`)
+
+---
+
 ## Components
 
 ---
@@ -381,7 +440,7 @@ const styles = StyleSheet.create({
 | `caption-sm` | 13 | 400 | `foregroundMuted` | Timestamps, metadata, helper text |
 | `badge-text` | 11 | 600 | `foreground` | Badge labels, small status tags |
 | `micro-label` | 12 | 700 | `foreground` | Micro labels, overlines |
-| `uppercase-tag` | 8 | 700 | `foreground` | Decorative uppercase category labels (auto-transforms text) |
+| `uppercase-tag` | 10 | 700 | `foreground` | Decorative uppercase category labels (auto-transforms text) |
 | `button-lg` | 16 | 500 | `foreground` | Internal use in Button component (md/lg) |
 | `button-sm` | 14 | 500 | `foreground` | Internal use in Button component (sm) |
 
@@ -456,7 +515,7 @@ const styles = StyleSheet.create({
 | `md` | 48px | 24px | 18px | `button-lg` (16pt/500) |
 | `lg` | 56px | 28px | 20px | `button-lg` (16pt/500) |
 
-**Shape:** `borderRadius: RADIUS.xl = 32px` — pill-shaped on all sizes.
+**Shape:** `borderRadius: RADIUS.md = 14px` — Airbnb-aligned rounded rect on all variants. Exception: `IconButton` uses `RADIUS.full` (perfect circle).
 
 **Animations:** Scale springs to 0.95 on `onPressIn`, back to 1.0 on `onPressOut`.
 
@@ -499,6 +558,67 @@ const styles = StyleSheet.create({
 
 ---
 
+### ButtonGroup
+
+**Import:** `import { ButtonGroup } from '@retray-dev/ui-kit'`
+
+**When to use:** Auto-distribute space equally between buttons in horizontal or vertical layouts. Perfect for side-by-side CTAs (Cancel/Confirm, Back/Next) where both buttons should occupy equal width.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `React.ReactNode` | required | Button components to lay out |
+| gap | `number` | `12` | Spacing between buttons (in points) |
+| vertical | `boolean` | `false` | Stack buttons vertically instead of horizontally |
+| style | `ViewStyle` | — | Override container style |
+
+**Behavior:** Automatically applies `flex: 1` to all direct children. Children share space equally regardless of label length.
+
+**Mobile best practice:** When using 2 buttons with icons in a ButtonGroup, use `size="sm"` to prevent text clipping on narrow screens:
+```tsx
+// ✅ Good — Small size prevents overflow
+<ButtonGroup>
+  <Button label="Cancel" variant="secondary" size="sm" iconName="x" onPress={handleCancel} />
+  <Button label="Confirm" size="sm" iconName="check" onPress={handleConfirm} />
+</ButtonGroup>
+
+// ❌ Avoid — Default size may clip text when icons present
+<ButtonGroup>
+  <Button label="Cancel" variant="secondary" iconName="x" onPress={handleCancel} />
+  <Button label="Confirm" iconName="check" onPress={handleConfirm} />
+</ButtonGroup>
+```
+
+**Examples:**
+```tsx
+// Horizontal pair (50%/50%)
+<ButtonGroup>
+  <Button label="Cancel" variant="secondary" onPress={handleCancel} />
+  <Button label="Confirm" onPress={handleConfirm} />
+</ButtonGroup>
+
+// Custom gap
+<ButtonGroup gap={8}>
+  <Button label="Back" variant="text" onPress={handleBack} />
+  <Button label="Next" onPress={handleNext} />
+</ButtonGroup>
+
+// Vertical stack
+<ButtonGroup vertical gap={8}>
+  <Button label="Primary Action" onPress={handlePrimary} />
+  <Button label="Secondary Action" variant="secondary" onPress={handleSecondary} />
+  <Button label="Delete" variant="destructive" onPress={handleDelete} />
+</ButtonGroup>
+
+// Three buttons (33%/33%/33%)
+<ButtonGroup gap={6}>
+  <Button label="1D" variant="secondary" size="sm" onPress={() => setRange('1d')} />
+  <Button label="1W" variant="secondary" size="sm" onPress={() => setRange('1w')} />
+  <Button label="1M" size="sm" onPress={() => setRange('1m')} />
+</ButtonGroup>
+```
+
+---
+
 ### IconButton
 
 **Import:** `import { IconButton } from '@retray-dev/ui-kit'`
@@ -682,6 +802,9 @@ const styles = StyleSheet.create({
 | error | `string` | — | Error text below; turns border destructive (2px) |
 | hint | `string` | — | Helper text below (hidden when `error` is set) |
 | rows | `number` | `4` | Minimum row count — each row ≈ 30px. Sets `numberOfLines` |
+| prefixIcon | `string` | — | Icon name from `@expo/vector-icons` rendered inside top-left corner |
+| prefixIconNode | `ReactNode` | — | Custom icon node rendered top-left |
+| prefixIconColor | `string` | — | Override prefix icon color. Defaults to `foregroundMuted` |
 | containerStyle | `ViewStyle` | — | Outer container style |
 | style | `TextStyle` | — | TextInput element style |
 
@@ -689,9 +812,9 @@ const styles = StyleSheet.create({
 
 **Examples:**
 ```tsx
-<Textarea label="Bio" placeholder="Tell us about yourself" rows={5} />
-<Textarea label="Review" hint="Be honest and helpful" />
-<Textarea label="Notes" error="Notes are required" rows={3} />
+<Textarea label="Bio" placeholder="Tell us about yourself" rows={5} prefixIcon="user" />
+<Textarea label="Review" hint="Be honest and helpful" prefixIcon="message-circle" />
+<Textarea label="Notes" error="Notes are required" rows={3} prefixIcon="edit-3" />
 ```
 
 ---
@@ -776,6 +899,9 @@ const [amount, setAmount] = useState(0)
 | prefix | `string` | `'$'` | Symbol prepended to formatted value |
 | showDecimals | `boolean` | `false` | Show two decimal places with comma separator (e.g. `$25.000,00`) |
 | textColor | `string` | — | Override text color. Defaults to `foreground` token |
+| variant | `'hero' \| 'large' \| 'medium' \| 'small'` | — | Predefined size (48/32/18/14pt). Overrides default 56pt |
+| autoScale | `boolean` | `false` | Enable `adjustsFontSizeToFit` — long values shrink to fit one line |
+| maxFontSize | `number` | — | Max font size when `autoScale` true. Defaults to variant size or 56pt |
 | style | `ViewStyle` | — | Outer container style |
 
 **Format:** Dot (`.`) as thousands separator, comma (`,`) as decimal separator — Latin American / European format.
@@ -874,9 +1000,10 @@ const [amount, setAmount] = useState(0)
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| src | `string` | — | Image URI (remote or local) |
-| fallback | `string` | — | Text shown when image fails or `src` is absent — first 2 characters shown, uppercased |
-| size | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Diameter in points |
+| src | `string \| null` | — | Image URI (remote or local). `null` forces fallback |
+| fallback | `string` | — | Manual initials (max 2 chars, uppercased) |
+| fallbackText | `string` | — | Full name — extracts up to 2 initials (e.g. `"Julian Cruz"` → `"JC"`) |
+| size | `'sm' \| 'md' \| 'lg' \| 'xl' \| number` | `'md'` | Named size or custom diameter in points |
 | status | `'online' \| 'offline' \| 'busy' \| 'away'` | — | Status indicator dot, bottom-right |
 | style | `ViewStyle` | — | — |
 
@@ -903,6 +1030,8 @@ const [amount, setAmount] = useState(0)
 <Avatar fallback="AN" size="md" />
 <Avatar src={user.avatar} fallback={user.initials} size="xl" status="online" />
 <Avatar fallback="BU" size="sm" status="busy" />
+<Avatar fallbackText="Julian Cruz" size="md" />  // → "JC"
+<Avatar src={avatarUrl} size={64} />              // custom numeric size
 
 // In a ListItem
 <ListItem
@@ -1773,7 +1902,14 @@ const [tab, setTab] = useState('profile')
 
 **AccordionItem type:**
 ```ts
-{ value: string; trigger: string; content: ReactNode }
+{
+  value: string
+  trigger: string
+  content: ReactNode
+  iconName?: string          // Icon name from @expo/vector-icons
+  icon?: ReactNode           // Custom icon node
+  iconColor?: string         // Override icon color (defaults to foregroundMuted)
+}
 ```
 
 **Animation:** `react-native-reanimated` `withTiming` (220ms) for height and chevron rotation (180°). Press scale uses `withSpring`. Runs on UI thread at 60fps.
@@ -1787,11 +1923,13 @@ const [tab, setTab] = useState('profile')
     {
       value: 'q1',
       trigger: 'What payment methods do you accept?',
+      iconName: 'credit-card',
       content: <Text variant="body-sm">We accept Visa, Mastercard, and bank transfers.</Text>,
     },
     {
       value: 'q2',
       trigger: 'Can I cancel my booking?',
+      iconName: 'x-circle',
       content: <Text variant="body-sm">Yes — free cancellation within 48 hours of booking.</Text>,
     },
   ]}
@@ -1808,7 +1946,7 @@ const [tab, setTab] = useState('profile')
 
 ### Sheet
 
-**Import:** `import { Sheet, BottomSheetModalProvider } from '@retray-dev/ui-kit'`
+**Import:** `import { Sheet, SheetTextInput, BottomSheetModalProvider } from '@retray-dev/ui-kit'`
 
 **When to use:** Bottom sheet for contextual actions, filters, pickers, or detail views that don't need a full screen. Auto-sizes to content — no snap points needed.
 
@@ -1825,158 +1963,156 @@ Add `react-native-worklets/plugin` (not `react-native-reanimated/plugin`) to `ba
 | open | `boolean` | required | `true` presents the sheet, `false` dismisses it |
 | onClose | `() => void` | required | Called on swipe-dismiss or backdrop press |
 | title | `string` | — | Sheet heading |
-| description | `string` | — | Supporting text below title |
+| subtitle | `string` | — | Supporting text below title (replaces deprecated `description`) |
+| showCloseButton | `boolean` | `false` | Show X close button in the header |
 | children | `ReactNode` | — | Sheet content |
-| style | `ViewStyle` | — | Inner content container style |
-| scrollable | `boolean` | `false` | Wraps children in `BottomSheetScrollView` — fixes gesture conflict on both platforms when content needs to scroll |
-| maxHeight | `number` | — | Caps sheet height (dp). Automatically enables scrolling when content exceeds this value |
+| style | `ViewStyle` | — | Inner scroll/content container style |
+| contentStyle | `ViewStyle` | — | Outer content wrapper style |
+| scrollable | `boolean` | `false` | Wraps children in `BottomSheetScrollView` |
+| maxHeight | `number` | `~85% screen` | Caps sheet height (dp). Defaults to 85% of screen height. Enables scrolling when content overflows |
+| keyboardBehavior | `'extend' \| 'fillParent' \| 'interactive'` | `'interactive'` | How sheet responds to keyboard. `'interactive'` (default) offsets sheet by keyboard size — works on both platforms. `'fillParent'` extends to fill parent view. `'extend'` extends to max snap point |
+| keyboardBlurBehavior | `'none' \| 'restore'` | `'restore'` | What happens when keyboard dismisses: `'restore'` → return to pre-keyboard position (recommended), `'none'` → stay at keyboard-adjusted position |
+| enableBlurKeyboardOnGesture | `boolean` | `true` | Dismiss keyboard when user starts dragging sheet down (recommended for better UX) |
+| android_keyboardInputMode | `'adjustPan' \| 'adjustResize'` | `'adjustPan'` | Android-only: `'adjustPan'` moves the window (default — fixes restore issues with dynamic sizing). `'adjustResize'` resizes the container (can cause transparent gap when keyboard dismisses) |
+| footer | `ReactNode` | — | Sticky footer below scroll area (sticky above keyboard) |
+| snapPoints | `(string \| number)[]` | — | Optional snap points (e.g., `['50%', '85%']`). When omitted, uses dynamic sizing (auto-fits content) |
 
 **Features:**
-- `enableDynamicSizing` — height auto-fits content, no `snapPoints` needed
+- `enableDynamicSizing` — height auto-fits content, no `snapPoints` needed (default behavior when `snapPoints` is omitted)
+- `snapPoints` — optionally provide custom snap points (e.g., `['50%', '85%']`). Disables dynamic sizing when provided
 - `enablePanDownToClose` — swipe down to dismiss
 - Backdrop press dismisses
-- **Scrollable content:** use `scrollable` prop (explicit) or `maxHeight` prop (capped height). Both use `BottomSheetScrollView` internally — do NOT use plain `ScrollView` inside Sheet, it breaks gesture handling on iOS
-
-**Styling:** `RADIUS.lg = 20px` top corners, 16px horizontal + 20px bottom padding.
-
-**Haptics:** `impactLight` on open.
+- **Scrollable content:** use `scrollable` prop or `maxHeight`. Both use `BottomSheetScrollView` — do NOT use plain `ScrollView` inside Sheet
+- **Keyboard handling:** Full keyboard awareness via `@gorhom/bottom-sheet` v5. Professional defaults:
+  - `keyboardBehavior="interactive"` — sheet offsets by keyboard size on both platforms
+  - `android_keyboardInputMode="adjustPan"` — moves window instead of resizing (fixes restore issues on Android)
+  - `keyboardBlurBehavior="restore"` — returns to pre-keyboard position when keyboard dismisses
+  - `enableBlurKeyboardOnGesture={true}` — dismisses keyboard when dragging sheet down
+  - `topInset` — automatically applied from safe area context to prevent going above notch
+- **Text inputs inside sheet:** **MUST use `SheetTextInput`** (re-exported `BottomSheetTextInput`) — handles focus/blur internally, communicates with sheet's keyboard system. **Never use regular `TextInput`** inside sheets — keyboard handling will break
+- **Custom TextInput:** If using custom input components, you must copy `handleOnFocus`/`handleOnBlur` from [BottomSheetTextInput source](https://github.com/gorhom/react-native-bottom-sheet/blob/master/src/components/bottomSheetTextInput/BottomSheetTextInput.tsx)
+
+**Haptics:** `impactMedium` on open.
 
 **Examples:**
 ```tsx
 const [open, setOpen] = useState(false)
 
+// Basic
 <Sheet open={open} onClose={() => setOpen(false)} title="Sort by">
-  <RadioGroup
-    options={[
-      { label: 'Newest', value: 'newest' },
-      { label: 'Price: Low to High', value: 'price_asc' },
-      { label: 'Price: High to Low', value: 'price_desc' },
-      { label: 'Rating', value: 'rating' },
-    ]}
-    value={sort}
-    onValueChange={(v) => { setSort(v); setOpen(false) }}
+  <RadioGroup options={sortOptions} value={sort} onValueChange={setSort} />
+</Sheet>
+
+// Scrollable list
+<Sheet open={open} onClose={() => setOpen(false)} title="Results" scrollable maxHeight={500}>
+  {items.map((r) => <ListItem key={r.id} title={r.name} showSeparator />)}
+</Sheet>
+
+// With text input — keyboard handling works automatically (platform-optimized defaults)
+<Sheet 
+  open={open} 
+  onClose={() => setOpen(false)} 
+  title="Add note"
+  subtitle="Keyboard handling is automatic with platform-optimized defaults" 
+>
+  <SheetTextInput 
+    placeholder="Write your note..." 
+    multiline
+    style={{ 
+      borderWidth: 1, 
+      borderColor: '#ddd',
+      borderRadius: 8,
+      padding: 12,
+      minHeight: 80,
+    }} 
   />
+  <Button label="Save" fullWidth style={{ marginTop: 12 }} onPress={() => setOpen(false)} />
 </Sheet>
 
-// Scrollable sheet — long list
-<Sheet open={open} onClose={() => setOpen(false)} title="Logs" scrollable>
-  {logs.map((log) => (
-    <Text key={log.id}>{log.message}</Text>
-  ))}
+// With custom snap points (manual sizing)
+<Sheet 
+  open={open} 
+  onClose={() => setOpen(false)} 
+  title="Filters"
+  snapPoints={['50%', '90%']}
+>
+  <RadioGroup options={filterOptions} value={filter} onValueChange={setFilter} />
 </Sheet>
 
-// Capped height — scroll kicks in when content overflows 400dp
-<Sheet open={open} onClose={() => setOpen(false)} title="Results" maxHeight={400}>
-  {results.map((r) => <ListItem key={r.id} title={r.name} />)}
+// With sticky footer
+<Sheet open={open} onClose={() => setOpen(false)} title="Filters" scrollable
+  footer={<View style={{ padding: 16 }}><Button label="Apply" fullWidth onPress={() => setOpen(false)} /></View>}>
+  {/* long filter content */}
 </Sheet>
 
-// Filter sheet
-<Sheet open={filterOpen} onClose={() => setFilterOpen(false)} title="Filters">
-  <View style={{ gap: SPACING.lg }}>
-    <View>
-      <Text variant="title-sm">Price range</Text>
-      <Slider value={maxPrice} minimumValue={0} maximumValue={1000} step={50} onValueChange={setMaxPrice} showValue formatValue={(v) => `$${v}`} />
-    </View>
-    <Separator />
-    <View>
-      <Text variant="title-sm">Category</Text>
-      <ChipGroup options={categoryOptions} value={selectedCategory} onValueChange={setSelectedCategory} />
-    </View>
-    <Button label="Apply filters" fullWidth onPress={() => { applyFilters(); setFilterOpen(false) }} />
-  </View>
+// With close button
+<Sheet open={open} onClose={() => setOpen(false)} title="Details" subtitle="Product info" showCloseButton>
+  <Text>Content here...</Text>
 </Sheet>
 ```
 
+**Keyboard handling notes:**
+- No `KeyboardAvoidingView` needed — `@gorhom/bottom-sheet` handles everything
+- Always use `SheetTextInput` (not plain `TextInput`) for auto-focus/blur handling
+- Default `keyboardBehavior="interactive"` works on both platforms
+- Default `android_keyboardInputMode="adjustPan"` fixes the transparent gap that occurs with `adjustResize` when keyboard dismisses
+- `enableBlurKeyboardOnGesture={true}` (default) dismisses keyboard when dragging sheet
+
 ---
 
 ### Toast / useToast
 
-**Import:** `import { ToastProvider, useToast } from '@retray-dev/ui-kit'`
+**Import:** `import { toast, ToastProvider, useToast } from '@retray-dev/ui-kit'`
 
 **When to use:** Ephemeral feedback messages — save confirmations, errors, copy notifications, background process updates. Auto-dismiss after duration.
 
-**Required setup:** `ToastProvider` must wrap app inside `SafeAreaProvider`. See Setup section above.
+**Powered by:** `sonner-native` — white/black background, colored icon marks the variant (not the background), swipe-to-dismiss, promise support, stacking.
+
+**Required setup:** `ToastProvider` must wrap the app. See Setup section above. Also requires `react-native-svg` and `react-native-screens` as peer deps.
 
-**Usage:**
+**API — direct function (preferred):**
 ```tsx
-function MyComponent() {
-  const { toast, dismiss } = useToast()
+import { toast } from '@retray-dev/ui-kit'
+
+// Variants:
+toast.success('Saved successfully')
+toast.error('Connection error', { description: 'Check your network' })
+toast.warning('Slow connection detected')
+toast('Neutral message')
+toast.loading('Processing...')
+
+// Promise — auto-resolves:
+toast.promise(saveData(), {
+  loading: 'Saving...',
+  success: 'Saved',
+  error: 'Failed to save',
+})
 
-  return (
-    <Button
-      label="Save"
-      onPress={async () => {
-        await save()
-        toast({ title: 'Saved', variant: 'success' })
-      }}
-    />
-  )
-}
+// Programmatic dismiss:
+const id = toast.loading('Uploading...')
+await upload()
+toast.dismiss(id)
+toast.success('Upload complete')
 ```
 
-**`toast()` options:**
-
-| Field | Type | Default | Notes |
-|-------|------|---------|-------|
-| title | `string` | — | Bold heading |
-| description | `string` | — | Detail text below title |
-| variant | `'default' \| 'destructive' \| 'success' \| 'warning'` | `'default'` | Background and icon color |
-| duration | `number` (ms) | `3000` | Auto-dismiss delay. Pass `Infinity` to prevent auto-dismiss |
-| icon | `ReactNode` | — | Custom icon. Defaults to variant symbol |
-| iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` |
-| iconColor | `string` | — | Override icon color |
-| action | `{ label: string, onPress: () => void }` | — | Optional action button beside dismiss |
-
-**`dismiss(id)`:** Dismiss a specific toast programmatically. `id` is returned by the `toast()` call.
-
-**Variant details:**
-- `default` — dark/primary background, `impactLight` haptic
-- `success` — `success` token background, `notificationSuccess` haptic
-- `destructive` — `destructive` token background, `notificationError` haptic
-- `warning` — `warning` token background, `notificationError` haptic
-
-**Behavior:**
-- Max 3 toasts shown simultaneously — oldest removed when 4th arrives
-- Appear at top of screen below status bar (dynamic safe area inset)
-- Swipe left or right to dismiss early (threshold: 80px or 800pt/s velocity)
-- **Web:** 400px max width, centered
-
-**Animation:** Entrance: `withTiming(120ms, Easing.out(Easing.exp))` slide-down + opacity. Exit: `withTiming(200ms)` slide-up + opacity fade.
-
-**Examples:**
+**API — hook (backward compat):**
 ```tsx
 const { toast, dismiss } = useToast()
-
-// Basic variants
-toast({ title: 'Saved', variant: 'success' })
-toast({ title: 'Connection error', variant: 'destructive' })
-toast({ title: 'Check your email', variant: 'warning' })
-toast({ title: 'Link copied' })
-
-// With description
-toast({
-  title: 'Payment sent',
-  description: '$250 sent to John Doe',
-  variant: 'success',
-  iconName: 'check-circle',
-})
-
-// With action button
-toast({
-  title: 'Message deleted',
-  action: { label: 'Undo', onPress: () => restoreMessage() },
-})
-
-// Custom duration (longer)
-toast({ title: 'Processing your request...', duration: 8000 })
-
-// Programmatic dismiss
-const id = toast({ title: 'Uploading...', duration: Infinity })
-await upload()
+toast.success('Saved')
 dismiss(id)
-toast({ title: 'Upload complete', variant: 'success' })
 ```
 
+**Behavior:**
+- Max 3 toasts shown simultaneously
+- Appear top-center with safe area insets (respects notch/status bar)
+- Swipe up to dismiss early
+- Auto-dismiss after 4000ms
+- Follows `colorScheme` from `ThemeProvider` (light/dark background)
+
+**Notes:**
+- `richColors: false` — background stays white (light) / black (dark). Variant shown via icon color only.
+- `closeButton: false` — swipe-to-dismiss is the gesture.
+
 ---
 
 ### ConfirmDialog
@@ -2049,6 +2185,8 @@ toast({ title: 'Upload complete', variant: 'success' })
 
 **When to use:** Rows in lists, feeds, menus, settings screens. The most compositional component — composes left slot, text block, and right slot in a standard horizontal layout. Supports plain (list items) and card (standalone cards) variants.
 
+**Important:** ListItem has **zero horizontal padding** by design — the consumer controls spacing. Wrap in a container with padding for standalone use, or use `variant="card"` for auto-styled surfaces.
+
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | title | `string` | required | Primary text |
@@ -2159,6 +2297,84 @@ toast({ title: 'Upload complete', variant: 'success' })
 
 ---
 
+### MenuItem
+
+**Import:** `import { MenuItem } from '@retray-dev/ui-kit'`
+
+**When to use:** Settings screens, navigation lists, menu entries — icon + label + optional right content. Purpose-built for Airbnb-style settings rows. Use `ListItem` when you need subtitle, caption, or more complex layouts.
+
+**Important:** MenuItem has **zero horizontal padding** by design — the consumer controls spacing. Wrap in a container with padding for standalone use, or use `variant="card"` for auto-styled surfaces.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| label | `string` | required | Row label |
+| iconName | `string` | — | Icon from `@expo/vector-icons`. Auto-resolved across all 6 families |
+| icon | `ReactNode` | — | Custom icon (used if `iconName` not set) |
+| iconColor | `string` | — | Override icon color. Defaults to `foreground` |
+| rightRender | `ReactNode` | — | Custom content on the right. Replaces default chevron. Use for Switch, Checkbox, Badge, etc. |
+| showChevron | `boolean` | `true` | Show chevron on the right. Ignored when `rightRender` is set |
+| onPress | `() => void` | required | Press handler |
+| variant | `'plain' \| 'card'` | `'plain'` | `plain` sits inside parent surface. `card` has own background + border |
+| disabled | `boolean` | `false` | Dims and disables press |
+| showSeparator | `boolean` | `false` | Hairline separator at bottom |
+| style | `ViewStyle` | — | Container style override |
+| labelStyle | `TextStyle` | — | Label text style override |
+
+**Features:**
+- Height: 54dp — consistent settings row
+- Chevron: shown by default (`showChevron={true}`). Can be replaced via `rightRender` prop
+- `rightRender` — arbitrary right slot content (Switch, Checkbox, Badge, etc). When set, chevron is hidden
+- Press scale: 0.97 spring (`stiffness: 350, damping: 28, mass: 0.9`)
+- Haptics: `selectionAsync` on press
+
+**Example:**
+```tsx
+// Settings screen (wrap in container with padding)
+<View style={{ padding: 16, backgroundColor: colors.card, borderRadius: 12 }}>
+  <MenuItem label="Personal info" iconName="user" onPress={() => navigate('profile')} showSeparator />
+  <MenuItem label="Security" iconName="shield" onPress={() => navigate('security')} showSeparator />
+  <MenuItem label="Privacy" iconName="lock" onPress={() => navigate('privacy')} showSeparator />
+  <MenuItem 
+    label="Notifications" 
+    iconName="bell" 
+    onPress={() => setNotifs(!notifs)}
+    rightRender={<Switch value={notifs} onValueChange={setNotifs} />}
+    showSeparator 
+  />
+  <MenuItem 
+    label="Dark Mode" 
+    iconName="moon" 
+    onPress={() => setDark(!dark)}
+    rightRender={<Checkbox checked={dark} onPress={() => setDark(!dark)} />}
+    showSeparator 
+  />
+  <MenuItem 
+    label="Payments" 
+    iconName="credit-card" 
+    onPress={() => navigate('payments')}
+    rightRender={<Badge label="New" variant="warning" size="sm" />}
+  />
+</View>
+
+// Card variant (standalone)
+<MenuItem
+  variant="card"
+  label="Refer a friend"
+  iconName="gift"
+  onPress={() => navigate('referral')}
+/>
+
+// No chevron (custom right content)
+<MenuItem
+  label="Language"
+  iconName="globe"
+  rightRender={<Text>English</Text>}
+  onPress={() => navigate('language')}
+/>
+```
+
+---
+
 ### Chip / ChipGroup
 
 **Import:** `import { Chip, ChipGroup } from '@retray-dev/ui-kit'`
@@ -2180,7 +2396,7 @@ toast({ title: 'Upload complete', variant: 'success' })
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| options | `ChipOption[]` | required | `{ label: string, value: string \| number }` |
+| options | `ChipOption[]` | required | `{ label, value, iconName?, iconColor?, disabled? }` |
 | value | `string \| number \| (string \| number)[]` | — | Selected value(s) |
 | onValueChange | `(value: ...) => void` | — | Returns single value or array depending on `multiSelect` |
 | multiSelect | `boolean` | `false` | Allow multiple chips selected simultaneously |
@@ -2325,29 +2541,98 @@ const [categories, setCategories] = useState<number[]>([1, 3])
 |------|------|---------|-------|
 | label | `string` | required | Caption label on the left |
 | value | `string \| ReactNode` | required | Value on the right. Strings auto-styled; pass `ReactNode` for custom content |
+| iconName | `string` | — | Icon name from `@expo/vector-icons` rendered left of label |
+| iconColor | `string` | — | Override icon color. Defaults to `foregroundMuted` |
 | style | `ViewStyle` | — | — |
 
 **Styling:** Row layout, `justifyContent: 'space-between'`. Label: 13pt / Regular / `foregroundMuted`. Value: 14pt / Medium / `foreground`. 12px gap.
 
 **Examples:**
 ```tsx
-<LabelValue label="Date" value="12 mar 2025" />
-<LabelValue label="Category" value="Food & drink" />
-<LabelValue label="Status" value={<Badge label="Pending" variant="warningOutline" size="sm" />} />
-<LabelValue label="Amount" value="$45.000" />
+<LabelValue label="Date" value="12 mar 2025" iconName="calendar" />
+<LabelValue label="Category" value="Food & drink" iconName="tag" />
+<LabelValue label="Status" value={<Badge label="Pending" variant="warningOutline" size="sm" />} iconName="clock" />
+<LabelValue label="Amount" value="$45.000" iconName="dollar-sign" />
 
 // Transaction detail
 <View style={{ gap: SPACING.sm }}>
-  <LabelValue label="Merchant" value={transaction.merchant} />
-  <LabelValue label="Date" value={formatDate(transaction.date)} />
-  <LabelValue label="Category" value={transaction.category} />
+  <LabelValue label="Merchant" value={transaction.merchant} iconName="shopping-bag" />
+  <LabelValue label="Date" value={formatDate(transaction.date)} iconName="calendar" />
+  <LabelValue label="Category" value={transaction.category} iconName="tag" />
   <Separator />
-  <LabelValue label="Amount" value={`$${transaction.amount}`} />
+  <LabelValue label="Amount" value={`$${transaction.amount}`} iconName="dollar-sign" />
 </View>
 ```
 
 ---
 
+### DetailRow
+
+**Import:** `import { DetailRow } from '@retray-dev/ui-kit'`
+
+**When to use:** "Label ··· Value" ticket/receipt rows — financial summaries, split bills, transaction breakdowns. Dotted separator fills the space between label and value.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| label | `string \| ReactNode` | required | Left side. Strings auto-styled in `foregroundMuted` caption |
+| value | `string` | required | Right side value text |
+| separator | `'dotted' \| 'solid' \| 'dashed' \| 'none'` | `'dotted'` | Fill line between label and value |
+| labelWeight | `'normal' \| 'medium' \| 'semibold' \| 'bold'` | `'normal'` | Font weight of label text |
+| valueColor | `string` | — | Override value text color (hex or theme token value) |
+| leftIcon | `ReactNode` | — | Node rendered left of label (e.g. `Avatar`, `Icon`) |
+| leftIconName | `string` | — | Icon name from `@expo/vector-icons` rendered left of label. Takes precedence over `leftIcon` |
+| leftIconColor | `string` | — | Override left icon color. Defaults to `foregroundMuted` |
+| rightIconName | `string` | — | Icon name from `@expo/vector-icons` rendered right of value |
+| rightIconColor | `string` | — | Override right icon color. Defaults to `foregroundMuted` |
+| style | `ViewStyle` | — | Row container style |
+| labelStyle | `TextStyle` | — | Label text style override |
+| valueStyle | `TextStyle` | — | Value text style override |
+
+**Examples:**
+```tsx
+// Basic
+<DetailRow label="Total" value="$50.000" />
+
+// With icons
+<DetailRow label="Food" value="$380.000" leftIconName="coffee" />
+<DetailRow label="Transport" value="$95.000" leftIconName="truck" />
+<DetailRow label="Total" value="$1.250.000" labelWeight="bold" rightIconName="trending-up" />
+
+// Dotted separator with bold total
+<DetailRow label="Total" value="$50.000" labelWeight="bold" />
+
+// With avatar left icon
+<DetailRow
+  label="Juliana"
+  value="$25.000"
+  leftIcon={<Avatar src={avatarUrl} size={20} />}
+/>
+
+// Destructive value
+<DetailRow label="Deuda" value="$150.000" valueColor={colors.destructive} />
+
+// No separator
+<DetailRow label="Subtotal" value="$45.000" separator="none" />
+
+// Full receipt block
+<View style={{ gap: SPACING.xs }}>
+  <DetailRow label="Juliana" value="$25.000" leftIcon={<Avatar fallback="J" size={20} />} />
+  <DetailRow label="Julián" value="$25.000" leftIcon={<Avatar fallback="JC" size={20} />} />
+  <Separator />
+  <DetailRow label="Total" value="$50.000" labelWeight="bold" />
+</View>
+```
+
+**Output:**
+```
+Juliana ············ $25.000
+Julián ············· $25.000
+─────────────────────────────
+Total ·············· $50.000
+```
+
+---
+
 ### MonthPicker
 
 **Import:** `import { MonthPicker } from '@retray-dev/ui-kit'`
@@ -2358,6 +2643,8 @@ const [categories, setCategories] = useState<number[]>([1, 3])
 |------|------|---------|-------|
 | value | `MonthPickerValue` | required | `{ month: 1–12, year: number }` |
 | onChange | `(value: MonthPickerValue) => void` | required | Called on navigation |
+| locale | `string` | `'en'` | BCP 47 locale. Built-in: `'en'`, `'es'`, `'pt'`, `'fr'`. Other locales: use `formatLabel` |
+| formatLabel | `(value: MonthPickerValue) => string` | — | Custom label formatter. Takes precedence over `locale` |
 | style | `ViewStyle` | — | — |
 
 **MonthPickerValue type:**
@@ -2381,6 +2668,16 @@ const [period, setPeriod] = useState({
 <MonthPicker value={period} onChange={setPeriod} />
 // Displays: "May 2026"
 
+<MonthPicker value={period} onChange={setPeriod} locale="es" />
+// Displays: "mayo 2026"
+
+<MonthPicker
+  value={period}
+  onChange={setPeriod}
+  formatLabel={({ month, year }) => `${month}/${year}`}
+/>
+// Displays: "5/2026"
+
 // In a transactions header
 <View style={{ flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center' }}>
   <Text variant="display-md">Transactions</Text>
@@ -2528,6 +2825,43 @@ All components with icon slots accept `iconName` — auto-resolved size and colo
 
 ---
 
+### `getResponsiveFontSize` utility
+
+Calculates a stepped-down font size for long numeric strings (currency amounts, large numbers) that would overflow at full size.
+
+```tsx
+import { getResponsiveFontSize } from '@retray-dev/ui-kit'
+
+// Default steps: ≤10 chars → max, ≤12 → max-4, ≤14 → max-6, >14 → max-8
+const fontSize = getResponsiveFontSize(formatCOP(amount), 48)
+
+<Text style={{ fontSize }} numberOfLines={1} adjustsFontSizeToFit>
+  {formatCOP(amount)}
+</Text>
+```
+
+**Signature:**
+```ts
+getResponsiveFontSize(
+  text: string,
+  maxSize: number,
+  steps?: { maxLen: number; subtract: number }[]
+): number
+```
+
+Custom steps example:
+```tsx
+getResponsiveFontSize(text, 48, [
+  { maxLen: 8,  subtract: 0 },
+  { maxLen: 11, subtract: 6 },
+  { maxLen: 14, subtract: 10 },
+])
+```
+
+**Alternative:** Use `<CurrencyDisplay autoScale maxFontSize={48} />` for currency values — no manual sizing needed.
+
+---
+
 ## Hover Support (Web)
 
 ```tsx
@@ -2592,3 +2926,29 @@ All `Text` and `TextInput` components have `allowFontScaling={true}` — respect
 
 ### Scaling utilities (internal)
 Used internally — not exported. `s()` horizontal scale, `vs()` vertical scale, `ms()` moderate scale relative to 350×680 base.
+
+---
+
+## Full Composition Examples
+
+The package includes **EXAMPLES.md** with complete, working code for 3 real-world app screens:
+
+1. **Finance Dashboard** — MonthPicker, CurrencyDisplay, Progress, CategoryStrip, ListItem, DetailRow
+2. **Edit Profile** — Avatar, Badge, Input, Select, Switch, Card, AlertBanner
+3. **Onboarding Flow** — Badge, Progress, Input, RadioGroup, EmptyState (multi-step wizard)
+
+**For AI agents:** Import EXAMPLES.md from the package for full source code and patterns:
+
+```markdown
+## UI Kit Composition Examples
+@./node_modules/@retray-dev/ui-kit/EXAMPLES.md
+```
+
+Each example includes:
+- Complete component code (copy-paste ready)
+- State management setup
+- Proper imports and theme usage
+- Common patterns (spacing, colors, navigation, toast feedback)
+- StyleSheet definitions
+
+**For human developers:** Examples are also live in the `example/` app. Clone the repo, run `pnpm install && pnpm build`, then `cd example && pnpm start` to see them in action. Access via "🖥 App Screen Compositions" accordion.