@retray-dev/ui-kit 5.4.0 → 6.0.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v5.4.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`.
 
@@ -1887,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.
 
@@ -1904,160 +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 |
-| keyboardBehavior | `'padding' \| 'height' \| 'position' \| 'none'` | — | Wraps content in `KeyboardAvoidingView` when set. Use when sheet contains text inputs |
-| keyboardOffset | `number` | `0` | Extra vertical offset for `KeyboardAvoidingView` |
+| 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
@@ -2130,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 |
@@ -2240,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'`