@retray-dev/ui-kit 2.3.0 → 2.5.1

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v2.1.0)
+# @retray-dev/ui-kit — Component Reference (v2.5.1)
 
 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:
 
@@ -121,12 +121,12 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 | color | `string` | — | Override the color. Defaults to `foreground`, except `caption` which uses `mutedForeground` |
 
 **Sizes:**
-- `h1`: 32px / 700 weight
-- `h2`: 24px / 700 weight
-- `h3`: 20px / 600 weight
-- `body`: 16px / 400 weight
-- `label`: 14px / 500 weight
-- `caption`: 12px / 400 weight / `mutedForeground` color by default
+- `h1`: 40px / 700 weight / lineHeight 52
+- `h2`: 28px / 700 weight / lineHeight 36
+- `h3`: 22px / 600 weight / lineHeight 30
+- `body`: 17px / 400 weight / lineHeight 26
+- `label`: 15px / 500 weight / lineHeight 22
+- `caption`: 13px / 400 weight / lineHeight 20 / `mutedForeground` color by default
 
 **Example:**
 ```tsx
@@ -152,7 +152,7 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 | loading | `boolean` | `false` | Replaces label with a spinner and forces disabled state |
 | fullWidth | `boolean` | `false` | Stretches to container width (`alignSelf: 'stretch'`) |
 | disabled | `boolean` | — | Reduces opacity to 0.5 |
-| icon | `React.ReactNode` | — | Icon rendered alongside the label |
+| icon | `React.ReactNode \| ((props: { label, size, variant }) => React.ReactNode)` | — | Icon rendered alongside the label. Can be a node or a render function |
 | iconPosition | `'left' \| 'right'` | `'left'` | Side the icon appears on |
 
 **Variants:**
@@ -162,7 +162,7 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 - `ghost`: fully transparent — in-context or low-emphasis actions
 - `destructive`: filled with `destructive` token — irreversible or dangerous actions
 
-**Animations:** Scale springs to 0.97 on `onPressIn`, back to 1.0 on `onPressOut`.
+**Animations:** Scale springs to 0.95 on `onPressIn`, back to 1.0 on `onPressOut`.
 
 **Example:**
 ```tsx
@@ -188,7 +188,10 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 | hint | `string` | — | Helper text below (hidden when `error` is set) |
 | prefix | `string \| ReactNode` | — | Content rendered before the input field (e.g., `"$"` or an icon) |
 | suffix | `string \| ReactNode` | — | Content rendered after the input field (e.g., `"kg"` or a button) |
+| prefixStyle | `TextStyle` | — | Style applied to the prefix text when prefix is a string |
+| suffixStyle | `TextStyle` | — | Style applied to the suffix text when suffix is a string |
 | type | `'text' \| 'password'` | `'text'` | When `'password'`, shows a visibility toggle button in the suffix slot |
+| containerStyle | `ViewStyle` | — | Style for the outer container `View` |
 
 **Border colors:** `destructive` when `error` is set, `ring` when focused, `border` otherwise.
 
@@ -260,7 +263,8 @@ const [amount, setAmount] = useState(0)
 | label | `string` | — | Label above |
 | error | `string` | — | Error text below; red border |
 | hint | `string` | — | Helper text below |
-| rows | `number` | `4` | Sets `minHeight` (each row ≈ 28px) |
+| rows | `number` | `4` | Sets `minHeight` (each row ≈ 30px) and `numberOfLines` |
+| containerStyle | `ViewStyle` | — | Style for the outer container `View` |
 
 **Example:**
 ```tsx
@@ -505,8 +509,8 @@ All sub-components (`CardHeader`, `CardTitle`, `CardDescription`, `CardContent`,
 **Notes:**
 - `CardHeader` and `CardContent` have `padding: 24`. Override via the `style` prop: `<CardContent style={{ padding: 16 }}>`
 - `CardFooter` has `paddingTop: 0` so it connects naturally to `CardContent`
-- `CardTitle`: 18px / 600 weight, `cardForeground` color
-- `CardDescription`: 14px, `mutedForeground` color
+- `CardTitle`: 20px / 600 weight / lineHeight 28, `cardForeground` color
+- `CardDescription`: 15px / lineHeight 22, `mutedForeground` color
 - Press animation scales to 0.98 via `Animated.spring` when `onPress` is provided
 
 ---
@@ -890,6 +894,7 @@ function MyComponent() {
 **Notes:**
 - Max 3 toasts shown simultaneously (oldest is removed when a 4th arrives)
 - Toasts appear at the top of the screen, below the status bar (dynamic safe area inset)
+- **On web:** constrained to 400px wide and centered (`alignSelf: 'center'`) — not full-width
 - Entrance: `withTiming(120ms, Easing.out(Easing.exp))` slide-down + opacity fade — fast, sharp feel
 - Exit: `withTiming(200ms)` slide-up + opacity fade
 - Swipe left or right to dismiss early (threshold: 80px or 800 pt/s velocity)
@@ -899,32 +904,81 @@ function MyComponent() {
 ### ListItem
 
 **Import:** `import { ListItem } from '@retray-dev/ui-kit'`
-**When to use:** Rows in a list or menu. Composes icon, title, subtitle, and trailing content in a standard horizontal layout.
+**When to use:** Rows in a list, feed, or menu. Composes a left slot (avatar, icon, image), title/subtitle/caption text block, and a right slot (price, badge, chevron, switch, etc.) in a standard horizontal layout. Supports both plain and card visual variants.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| title | `string` | required | Primary label |
-| subtitle | `string` | — | Secondary label below the title |
-| icon | `ReactNode` | — | Node rendered to the left of the text content |
-| trailing | `string \| ReactNode` | — | Content on the right edge. Strings are styled as muted caption |
-| onPress | `() => void` | — | Makes the row pressable. Scale animation + haptics are only active when provided |
+| title | `string` | required | Primary text (17px / 500 weight) |
+| subtitle | `string` | — | Secondary line below the title (14px / 400 weight) |
+| caption | `string` | — | Tertiary / caption line below the subtitle (12px / 400 weight, 70% opacity) |
+| leftRender | `ReactNode` | — | Arbitrary content in a fixed 44×44pt left slot (avatar, icon, image, etc.) |
+| rightRender | `string \| ReactNode` | — | Content on the right edge. Strings are styled as muted text (15px); pass ReactNode for Badges, prices, switches, etc. |
+| variant | `'plain' \| 'card'` | `'plain'` | `plain`: no background, sits inside a parent surface. `card`: standalone surface with background, border, and shadow |
+| showChevron | `boolean` | `false` | Shows a `›` chevron on the far right. Ignored when `rightRender` is set |
+| showSeparator | `boolean` | `false` | Renders a hairline separator at the bottom. Useful when stacking multiple plain items in a list |
+| onPress | `() => void` | — | Makes the row pressable (scale spring + haptics). No animation or haptics when omitted |
 | disabled | `boolean` | — | Reduces opacity to 0.45 |
-| style | `ViewStyle` | — | — |
+| style | `ViewStyle` | — | Style applied to the outer container |
+| titleStyle | `TextStyle` | — | Style override for the title text |
+| subtitleStyle | `TextStyle` | — | Style override for the subtitle text |
+| captionStyle | `TextStyle` | — | Style override for the caption text |
+| icon | `ReactNode` | — | **Deprecated** — use `leftRender` |
+| trailing | `string \| ReactNode` | — | **Deprecated** — use `rightRender` |
+
+**Animation:** Scale springs to 0.97 on press-in, back to 1.0 on press-out (only when `onPress` is provided).
 
 **Example:**
 ```tsx
+// Simple row with chevron
+<ListItem
+  title="Profile"
+  subtitle="Manage your account"
+  showChevron
+  onPress={() => navigate('profile')}
+/>
+
+// Rich row: avatar + title/subtitle/caption + price + badge
 <ListItem
-  icon={<Ionicons name="receipt-outline" size={18} />}
-  title="Mercado"
-  subtitle="12 mar 2025"
-  trailing="$45.000"
-  onPress={() => navigate('detail')}
+  leftRender={<Avatar src={item.avatar} fallback={item.initials} size="md" />}
+  title={item.name}
+  subtitle={item.date}
+  caption={item.category}
+  rightRender={
+    <View style={{ alignItems: 'flex-end', gap: 4 }}>
+      <Text variant="label">${item.amount}</Text>
+      <Badge label={item.status} variant="secondary" size="sm" />
+    </View>
+  }
+  onPress={() => navigate('detail', { id: item.id })}
 />
 
-// Non-interactive row
-<ListItem title="Account number" trailing="**** 4321" />
+// Card variant (standalone surface)
+<ListItem
+  variant="card"
+  leftRender={<Ionicons name="wallet-outline" size={20} />}
+  title="Balance"
+  subtitle="Available funds"
+  rightRender="$12.500"
+/>
+
+// List with separators
+{transactions.map((t, i) => (
+  <ListItem
+    key={t.id}
+    title={t.name}
+    subtitle={t.date}
+    rightRender={t.amount}
+    showSeparator={i < transactions.length - 1}
+    onPress={() => navigate('detail', { id: t.id })}
+  />
+))}
 ```
 
+**Notes:**
+- `leftRender` renders inside a fixed 44×44pt container (centered) — no need to wrap in a sized View
+- `rightRender` container has `maxWidth: 160` and aligns content to the right edge
+- The separator inset aligns to the text block: `marginLeft: 16 + 44 + 12` when `leftRender` is set, `marginLeft: 16` otherwise
+
 ---
 
 ### Chip / ChipGroup

package/README.md

@@ -23,7 +23,7 @@ pnpm add @retray-dev/ui-kit
 Install these in your app if not already present:
 
 ```bash
-pnpm add expo-haptics react-native-safe-area-context @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-worklets
+pnpm add expo-haptics expo-linear-gradient react-native-safe-area-context @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-worklets @react-native-picker/picker @react-native-community/slider @expo/vector-icons
 ```
 
 For Expo projects, run `npx expo install` instead to get SDK-compatible versions.
@@ -100,7 +100,7 @@ const { colors, colorScheme } = useTheme()
 | Category    | Components                                                                                      |
 | ----------- | ----------------------------------------------------------------------------------------------- |
 | Display     | `Text`, `Badge`, `Avatar`, `Separator`, `Spinner`, `Skeleton`, `Progress`, `CurrencyDisplay`   |
-| Surfaces    | `Card`, `Alert`, `EmptyState`                                                                   |
+| Surfaces    | `Card`, `AlertBanner`, `EmptyState`                                                             |
 | Form        | `Button`, `Input`, `CurrencyInput`, `CurrencyInputLarge`, `Textarea`, `Checkbox`, `Switch`, `Toggle`, `RadioGroup`, `Select`, `Slider` |
 | Composition | `Tabs`, `Accordion`                                                                             |
 | Overlays    | `Sheet`, `ConfirmDialog`                                                                        |
@@ -116,9 +116,7 @@ import {
 } from '@retray-dev/ui-kit'
 
 // Button
-<Button variant="default" size="md" onPress={() => {}}>
-  Save
-</Button>
+<Button label="Save" variant="primary" size="md" onPress={() => {}} />
 
 // Toast
 const { toast } = useToast()

package/dist/index.d.mts

@@ -430,16 +430,48 @@ interface CurrencyDisplayProps {
 }
 declare function CurrencyDisplay({ value, prefix, showDecimals, textColor, style }: CurrencyDisplayProps): React.JSX.Element;
 
+type ListItemVariant = 'plain' | 'card';
 interface ListItemProps {
+    /**
+     * Arbitrary content rendered on the left (avatar, icon, image, etc.).
+     * Rendered inside a 44×44 aligned container.
+     */
+    leftRender?: React.ReactNode;
+    /**
+     * Arbitrary content rendered on the right (badge, price, chevron, switch, etc.).
+     * Replaces the old `trailing` prop (still accepted as an alias).
+     */
+    rightRender?: React.ReactNode | string;
+    /** @deprecated Use `rightRender` instead. */
+    trailing?: React.ReactNode | string;
+    /** @deprecated Use `leftRender` instead. */
     icon?: React.ReactNode;
     title: string;
+    /** Secondary line below the title. */
     subtitle?: string;
-    trailing?: string | React.ReactNode;
+    /** Tertiary / caption line below the subtitle. */
+    caption?: string;
+    /**
+     * - `plain` (default): no background, no border — designed to sit inside a parent surface (Card, list wrapper, etc.)
+     * - `card`: standalone surface with background, border and shadow.
+     */
+    variant?: ListItemVariant;
+    /** Show a right-pointing chevron on the far right. Ignored when `rightRender` / `trailing` is set. */
+    showChevron?: boolean;
+    /** Visual separator line at the bottom of the item. Useful when rendering multiple plain items in a list. */
+    showSeparator?: boolean;
     onPress?: () => void;
     disabled?: boolean;
+    /** Style applied to the outer container. */
     style?: ViewStyle;
-}
-declare function ListItem({ icon, title, subtitle, trailing, onPress, disabled, style }: ListItemProps): React.JSX.Element;
+    /** Style applied to the title Text. */
+    titleStyle?: TextStyle;
+    /** Style applied to the subtitle Text. */
+    subtitleStyle?: TextStyle;
+    /** Style applied to the caption Text. */
+    captionStyle?: TextStyle;
+}
+declare function ListItem({ leftRender, rightRender, trailing, icon, title, subtitle, caption, variant, showChevron, showSeparator, onPress, disabled, style, titleStyle, subtitleStyle, captionStyle, }: ListItemProps): React.JSX.Element;
 
 interface ChipProps {
     label: string;

package/dist/index.d.ts

@@ -430,16 +430,48 @@ interface CurrencyDisplayProps {
 }
 declare function CurrencyDisplay({ value, prefix, showDecimals, textColor, style }: CurrencyDisplayProps): React.JSX.Element;
 
+type ListItemVariant = 'plain' | 'card';
 interface ListItemProps {
+    /**
+     * Arbitrary content rendered on the left (avatar, icon, image, etc.).
+     * Rendered inside a 44×44 aligned container.
+     */
+    leftRender?: React.ReactNode;
+    /**
+     * Arbitrary content rendered on the right (badge, price, chevron, switch, etc.).
+     * Replaces the old `trailing` prop (still accepted as an alias).
+     */
+    rightRender?: React.ReactNode | string;
+    /** @deprecated Use `rightRender` instead. */
+    trailing?: React.ReactNode | string;
+    /** @deprecated Use `leftRender` instead. */
     icon?: React.ReactNode;
     title: string;
+    /** Secondary line below the title. */
     subtitle?: string;
-    trailing?: string | React.ReactNode;
+    /** Tertiary / caption line below the subtitle. */
+    caption?: string;
+    /**
+     * - `plain` (default): no background, no border — designed to sit inside a parent surface (Card, list wrapper, etc.)
+     * - `card`: standalone surface with background, border and shadow.
+     */
+    variant?: ListItemVariant;
+    /** Show a right-pointing chevron on the far right. Ignored when `rightRender` / `trailing` is set. */
+    showChevron?: boolean;
+    /** Visual separator line at the bottom of the item. Useful when rendering multiple plain items in a list. */
+    showSeparator?: boolean;
     onPress?: () => void;
     disabled?: boolean;
+    /** Style applied to the outer container. */
     style?: ViewStyle;
-}
-declare function ListItem({ icon, title, subtitle, trailing, onPress, disabled, style }: ListItemProps): React.JSX.Element;
+    /** Style applied to the title Text. */
+    titleStyle?: TextStyle;
+    /** Style applied to the subtitle Text. */
+    subtitleStyle?: TextStyle;
+    /** Style applied to the caption Text. */
+    captionStyle?: TextStyle;
+}
+declare function ListItem({ leftRender, rightRender, trailing, icon, title, subtitle, caption, variant, showChevron, showSeparator, onPress, disabled, style, titleStyle, subtitleStyle, captionStyle, }: ListItemProps): React.JSX.Element;
 
 interface ChipProps {
     label: string;