@retray-dev/ui-kit 2.3.0 → 2.5.0

package/COMPONENTS.md

@@ -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
@@ -890,6 +890,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 +900,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/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;