@retray-dev/ui-kit 1.8.0 → 2.5.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v1.8.0)
+# @retray-dev/ui-kit — Component Reference (v2.1.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:
 
@@ -74,7 +74,7 @@ function MyComponent() {
 
 ## Theme Tokens
 
-All 20 tokens are available via `useTheme().colors`.
+All 20 tokens are available via `useTheme().colors` and are applied exactly as provided — there is no automatic color derivation or forced contrast applied by the library. Consumers may pass partial overrides for `light` and/or `dark` and the values are used as-is.
 
 The `ThemeColors` type (and `Theme`, `ColorScheme`) are exported directly from the package:
 ```ts
@@ -85,23 +85,23 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 |-------|-------|------|---------------|
 | `background` | `#ffffff` | `#171717` | Screen / page background |
 | `foreground` | `#171717` | `#fafafa` | Primary text color |
-| `card` | `#ffffff` | `#1f1f1f` | Card / surface background |
+| `card` | `#ffffff` | `#222222` | Card / surface background |
 | `cardForeground` | `#171717` | `#fafafa` | Text on cards |
 | `primary` | `#1a1a1a` | `#fafafa` | Primary action (buttons, selected states) |
-| `primaryForeground` | `#fafafa` | `#1a1a1a` | Text/icon on primary background |
-| `secondary` | `#f5f5f5` | `#2a2a2a` | Secondary surfaces |
-| `secondaryForeground` | `#1a1a1a` | `#fafafa` | Text on secondary |
-| `muted` | `#f5f5f5` | `#2a2a2a` | Muted backgrounds, skeleton fills, track fills |
-| `mutedForeground` | `#646464` | `#a3a3a3` | Placeholder text, helper text, captions (WCAG AA ≥4.5:1) |
-| `accent` | `#f5f5f5` | `#2a2a2a` | Hover / pressed state fills |
-| `accentForeground` | `#1a1a1a` | `#fafafa` | Text on accent |
+| `primaryForeground` | `#ffffff` | `#1a1a1a` | Text/icon on primary background |
+| `secondary` | `#f1f1f1` | `#323232` | Secondary surfaces |
+| `secondaryForeground` | `#171717` | `#fafafa` | Text on secondary |
+| `muted` | `#f1f1f1` | `#323232` | Muted backgrounds, skeleton fills, track fills |
+| `mutedForeground` | `#a2a2a2` | `#888888` | Placeholder text, helper text, captions |
+| `accent` | `#e4e4e4` | `#323232` | Hover / pressed state fills |
+| `accentForeground` | `#171717` | `#fafafa` | Text on accent |
 | `destructive` | `#ef4444` | `#dc2626` | Error / danger / delete actions |
-| `destructiveForeground` | `#fafafa` | `#fafafa` | Text on destructive |
+| `destructiveForeground` | `#1a1a1a` | `#1a1a1a` | Text on destructive |
 | `border` | `#e5e5e5` | `#2a2a2a` | Borders and dividers |
 | `input` | `#e5e5e5` | `#2a2a2a` | Input field border color |
-| `ring` | `#a3a3a3` | `#d4d4d4` | Focus ring color |
+| `ring` | `#1a1a1a` | `#fafafa` | Optional focus ring token (components may use `primary` by default) |
 | `success` | `#16a34a` | `#22c55e` | Success state (Toast success variant) |
-| `successForeground` | `#ffffff` | `#ffffff` | Text on success background |
+| `successForeground` | `#1a1a1a` | `#1a1a1a` | Text on success background |
 
 ---
 
@@ -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
@@ -151,7 +151,7 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 | size | `'sm' \| 'md' \| 'lg'` | `'md'` | — |
 | 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.45 |
+| disabled | `boolean` | — | Reduces opacity to 0.5 |
 | icon | `React.ReactNode` | — | Icon rendered alongside the label |
 | iconPosition | `'left' \| 'right'` | `'left'` | Side the icon appears on |
 
@@ -186,14 +186,19 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 | label | `string` | — | Label above the input |
 | error | `string` | — | Shows error text below; turns border red (`destructive` token) |
 | 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) |
+| type | `'text' \| 'password'` | `'text'` | When `'password'`, shows a visibility toggle button in the suffix slot |
 
 **Border colors:** `destructive` when `error` is set, `ring` when focused, `border` otherwise.
 
 **Example:**
 ```tsx
 <Input label="Email" placeholder="you@example.com" keyboardType="email-address" />
-<Input label="Password" secureTextEntry error="Incorrect password" />
+<Input label="Password" type="password" error="Incorrect password" />
 <Input label="Username" hint="Must be at least 4 characters" />
+<Input label="Amount" prefix="$" placeholder="0.00" keyboardType="numeric" />
+<Input label="Weight" suffix="kg" placeholder="0" />
 ```
 
 ---
@@ -210,6 +215,7 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 | onChangeValue | `(raw: number) => void` | — | Called with the parsed number (no separators, no prefix) |
 | prefix | `string` | `'$'` | Symbol prepended to the formatted value |
 | thousandsSeparator | `'.' \| ','` | `'.'` | Character used to separate groups of three digits |
+| size | `'default' \| 'large'` | `'default'` | `'large'` uses 36px font size (previously `CurrencyInputLarge`) |
 | label | `string` | — | Label above the input |
 | error | `string` | — | Error text below; turns border red |
 | hint | `string` | — | Helper text below (hidden when `error` is set) |
@@ -270,16 +276,20 @@ const [amount, setAmount] = useState(0)
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| label | `string` | required | — |
+| label | `string` | — | Badge text — can be omitted if using `children` |
+| children | `ReactNode` | — | Alternative to `label` for custom content |
 | variant | `'default' \| 'secondary' \| 'destructive' \| 'outline'` | `'default'` | — |
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | Controls padding and font size |
+| icon | `ReactNode` | — | Icon rendered before the label/children |
 | style | `ViewStyle` | — | — |
 
 **Example:**
 ```tsx
 <Badge label="New" />
 <Badge label="Error" variant="destructive" />
-<Badge label="Draft" variant="secondary" />
+<Badge label="Draft" variant="secondary" size="sm" />
 <Badge label="Beta" variant="outline" />
+<Badge icon={<CheckIcon size={12} />} size="sm">Verified</Badge>
 ```
 
 ---
@@ -458,11 +468,20 @@ const [amount, setAmount] = useState(0)
 **Import:** `import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@retray-dev/ui-kit'`
 **When to use:** Grouped content with a surface background, border, and shadow.
 
-All sub-components accept a `style` prop for overrides.
+**`Card` Props:**
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| variant | `'elevated' \| 'outlined' \| 'filled'` | `'elevated'` | `elevated`: shadow + border; `outlined`: border only; `filled`: background fill, no border |
+| onPress | `() => void` | — | Makes the card pressable with scale animation + haptics |
+| children | `ReactNode` | — | — |
+| style | `ViewStyle` | — | — |
+
+All sub-components (`CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`) accept a `style` prop for overrides.
 
 **Example:**
 ```tsx
-<Card>
+<Card variant="elevated">
   <CardHeader>
     <CardTitle>Account</CardTitle>
     <CardDescription>Manage your profile settings</CardDescription>
@@ -474,6 +493,13 @@ All sub-components accept a `style` prop for overrides.
     <Button label="Save" fullWidth />
   </CardFooter>
 </Card>
+
+// Pressable card
+<Card variant="outlined" onPress={() => navigate('detail')}>
+  <CardContent>
+    <Text>Tap me</Text>
+  </CardContent>
+</Card>
 ```
 
 **Notes:**
@@ -481,6 +507,7 @@ All sub-components accept a `style` prop for overrides.
 - `CardFooter` has `paddingTop: 0` so it connects naturally to `CardContent`
 - `CardTitle`: 18px / 600 weight, `cardForeground` color
 - `CardDescription`: 14px, `mutedForeground` color
+- Press animation scales to 0.98 via `Animated.spring` when `onPress` is provided
 
 ---
 
@@ -638,7 +665,7 @@ const [accepted, setAccepted] = useState(false)
 ### Select
 
 **Import:** `import { Select } from '@retray-dev/ui-kit'`
-**When to use:** Dropdown picker. Tapping the trigger opens a modal with a scrollable list.
+**When to use:** Dropdown picker. Uses the native system picker UI on each platform — wheel modal on iOS (confirm with "Done"), spinner dialog on Android, native `<select>` on web (full keyboard support). Requires `@react-native-picker/picker` installed in the consuming app.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
@@ -678,13 +705,27 @@ const [accepted, setAccepted] = useState(false)
 | onValueChange | `(value: number) => void` | — | Fires while dragging |
 | onSlidingComplete | `(value: number) => void` | — | Fires on finger release |
 | disabled | `boolean` | — | — |
+| label | `string` | — | Label text displayed above the slider |
+| showValue | `boolean` | `false` | When `true`, displays the current value at the top right |
+| formatValue | `(value: number) => string` | — | Custom formatter for the displayed value |
+| accessibilityLabel | `string` | — | Accessibility label for screen readers |
 | style | `ViewStyle` | — | — |
 
-**Dimensions:** Container height=32pt, track height=6pt, thumb 28×28pt. Uses `PanResponder` internally.
+**Notes:** Uses `@react-native-community/slider` natively — theming applied via `minimumTrackTintColor` (primary), `maximumTrackTintColor` (muted), `thumbTintColor` (primary). Requires `@react-native-community/slider` installed in the consuming app.
 
 **Example:**
 ```tsx
 <Slider value={volume} minimumValue={0} maximumValue={100} step={1} onValueChange={setVolume} />
+<Slider 
+  label="Volume" 
+  showValue 
+  value={volume} 
+  minimumValue={0} 
+  maximumValue={100} 
+  step={5}
+  formatValue={(v) => `${v}%`}
+  onValueChange={setVolume} 
+/>
 ```
 
 ---
@@ -849,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)
@@ -858,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
-  icon={<Ionicons name="receipt-outline" size={18} />}
-  title="Mercado"
-  subtitle="12 mar 2025"
-  trailing="$45.000"
-  onPress={() => navigate('detail')}
+  title="Profile"
+  subtitle="Manage your account"
+  showChevron
+  onPress={() => navigate('profile')}
 />
 
-// Non-interactive row
-<ListItem title="Account number" trailing="**** 4321" />
+// Rich row: avatar + title/subtitle/caption + price + badge
+<ListItem
+  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 })}
+/>
+
+// 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
@@ -905,14 +996,16 @@ function MyComponent() {
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | options | `ChipOption[]` | required | Each: `{ label: string, value: string \| number }` |
-| value | `string \| number` | — | Currently selected value |
-| onValueChange | `(value: string \| number) => void` | — | — |
+| value | `string \| number \| (string \| number)[]` | — | Currently selected value (single mode) or array of selected values (multi mode) |
+| onValueChange | `(value: string \| number \| (string \| number)[]) => void` | — | — |
+| multiSelect | `boolean` | `false` | When `true`, allows multiple chips to be selected simultaneously |
 | style | `ViewStyle` | — | Applied to the wrapping row |
 
 **Animation:** Background, text, and border colors animate via `Animated.timing` (150ms) between unselected (`secondary`/`border`/`foreground`) and selected (`primary`/`primary`/`primaryForeground`) states.
 
 **Example:**
 ```tsx
+// Single select
 const [pct, setPct] = useState(50)
 
 <ChipGroup
@@ -924,6 +1017,20 @@ const [pct, setPct] = useState(50)
   value={pct}
   onValueChange={setPct}
 />
+
+// Multi select
+const [categories, setCategories] = useState<number[]>([1, 3])
+
+<ChipGroup
+  multiSelect
+  options={[
+    { label: 'Food', value: 1 },
+    { label: 'Transport', value: 2 },
+    { label: 'Entertainment', value: 3 },
+  ]}
+  value={categories}
+  onValueChange={setCategories}
+/>
 ```
 
 ---

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { TouchableOpacityProps, TextProps as TextProps$1, TextInputProps, ViewStyle, TextStyle, ActivityIndicatorProps } from 'react-native';
+import { TouchableOpacityProps, TextProps as TextProps$1, TextInputProps, TextStyle, ViewStyle, ActivityIndicatorProps } from 'react-native';
 export { BottomSheetModalProvider } from '@gorhom/bottom-sheet';
 
 type ThemeColors = {
@@ -36,11 +36,10 @@ type ThemeContextValue = {
 interface ThemeProviderProps {
     children: React.ReactNode;
     /**
-     * Override individual color tokens per scheme. Only provide the tokens you want
-     * to change — the rest fall back to the defaults.
-     * @example
-     * { light: { primary: '#6366f1', primaryForeground: '#fff' },
-     *   dark:  { primary: '#818cf8', primaryForeground: '#fff' } }
+    * Optional full-palette overrides per scheme. Supply a partial or full `ThemeColors` object
+    * for `light` and/or `dark` to override the defaults.
+    * @example
+    * { light: { primary: '#6366f1', card: '#fff' }, dark: { primary: '#818cf8' } }
      */
     theme?: Theme;
     /**
@@ -94,21 +93,42 @@ interface InputProps extends TextInputProps {
     error?: string;
     /** Helper text shown below the input when there is no error. */
     hint?: string;
-    /** Style for the outer container `View`. Use `style` (from `TextInputProps`) to style the `TextInput` itself. */
+    /** Text or component rendered before the input text. */
+    prefix?: React.ReactNode;
+    /** Text or component rendered after the input text. */
+    suffix?: React.ReactNode;
+    /** Style applied to prefix text if prefix is a string. */
+    prefixStyle?: TextStyle;
+    /** Style applied to suffix text if suffix is a string. */
+    suffixStyle?: TextStyle;
+    /** Input type. When set to \`'password'\`, shows a toggle button to reveal/hide text. */
+    type?: 'text' | 'password';
+    /** Style for the outer container \`View\`. Use \`style\` (from \`TextInputProps\`) to style the \`TextInput\` itself. */
     containerStyle?: ViewStyle;
 }
-declare function Input({ label, error, hint, containerStyle, style, onFocus, onBlur, ...props }: InputProps): React.JSX.Element;
+declare function Input({ label, error, hint, prefix, suffix, prefixStyle, suffixStyle, type, containerStyle, style, onFocus, onBlur, secureTextEntry, ...props }: InputProps): React.JSX.Element;
 
 type BadgeVariant = 'default' | 'secondary' | 'destructive' | 'outline';
+type BadgeSize = 'sm' | 'md' | 'lg';
 interface BadgeProps {
-    label: string;
+    label?: string;
+    /** Alternative to \`label\` — allows JSX children. */
+    children?: React.ReactNode;
     variant?: BadgeVariant;
+    size?: BadgeSize;
+    /** Icon rendered before the label/children. */
+    icon?: React.ReactNode;
     style?: ViewStyle;
 }
-declare function Badge({ label, variant, style }: BadgeProps): React.JSX.Element;
+declare function Badge({ label, children, variant, size, icon, style }: BadgeProps): React.JSX.Element;
 
+type CardVariant = 'elevated' | 'outlined' | 'filled';
 interface CardProps {
     children: React.ReactNode;
+    /** Visual style variant.  `'elevated'` (default) has shadow, `'outlined'` has border only, `'filled'` uses accent background. */
+    variant?: CardVariant;
+    /** Makes the card tappable. Adds press animation and haptic feedback. */
+    onPress?: () => void;
     style?: ViewStyle;
 }
 interface CardHeaderProps {
@@ -131,7 +151,7 @@ interface CardFooterProps {
     children: React.ReactNode;
     style?: ViewStyle;
 }
-declare function Card({ children, style }: CardProps): React.JSX.Element;
+declare function Card({ children, variant, onPress, style }: CardProps): React.JSX.Element;
 declare function CardHeader({ children, style }: CardHeaderProps): React.JSX.Element;
 declare function CardTitle({ children, style }: CardTitleProps): React.JSX.Element;
 declare function CardDescription({ children, style }: CardDescriptionProps): React.JSX.Element;
@@ -303,20 +323,20 @@ interface AccordionProps {
 declare function Accordion({ items, type, defaultValue, style }: AccordionProps): React.JSX.Element;
 
 interface SliderProps {
-    /** Current value. Controlled when provided; falls back to internal state otherwise. */
     value?: number;
     minimumValue?: number;
     maximumValue?: number;
-    /** Snap interval. `0` (default) means continuous (no snapping). */
     step?: number;
-    /** Called on every move while dragging. */
     onValueChange?: (value: number) => void;
-    /** Called once when the user releases the thumb. */
     onSlidingComplete?: (value: number) => void;
+    label?: string;
+    showValue?: boolean;
+    formatValue?: (value: number) => string;
+    accessibilityLabel?: string;
     disabled?: boolean;
     style?: ViewStyle;
 }
-declare function Slider({ value, minimumValue, maximumValue, step, onValueChange, onSlidingComplete, disabled, style, }: SliderProps): React.JSX.Element;
+declare function Slider({ value, minimumValue, maximumValue, step, onValueChange, onSlidingComplete, label, showValue, formatValue, accessibilityLabel, disabled, style, }: SliderProps): React.JSX.Element;
 
 interface SheetProps {
     open: boolean;
@@ -343,10 +363,8 @@ interface SelectProps {
     options: SelectOption[];
     value?: string;
     onValueChange?: (value: string) => void;
-    /** Text shown when no option is selected. Defaults to `'Select an option'`. */
     placeholder?: string;
     label?: string;
-    /** Red helper text; also changes trigger border to `destructive` color. */
     error?: string;
     disabled?: boolean;
     style?: ViewStyle;
@@ -387,6 +405,8 @@ interface CurrencyInputProps {
     prefix?: string;
     /** Character used to separate groups of three digits. Defaults to `'.'`. */
     thousandsSeparator?: '.' | ',';
+    /** Font size variant. `'large'` renders at 36pt, `'default'` at 17pt. */
+    size?: 'default' | 'large';
     label?: string;
     /** Red helper text; also changes input border to destructive color. */
     error?: string;
@@ -394,8 +414,9 @@ interface CurrencyInputProps {
     placeholder?: string;
     editable?: boolean;
     containerStyle?: ViewStyle;
+    style?: TextStyle;
 }
-declare function CurrencyInput({ value, onChangeText, onChangeValue, prefix, thousandsSeparator, label, error, hint, placeholder, editable, containerStyle, }: CurrencyInputProps): React.JSX.Element;
+declare function CurrencyInput({ value, onChangeText, onChangeValue, prefix, thousandsSeparator, size, label, error, hint, placeholder, editable, containerStyle, style, }: CurrencyInputProps): React.JSX.Element;
 
 interface CurrencyDisplayProps {
     value: number | string;
@@ -409,35 +430,48 @@ interface CurrencyDisplayProps {
 }
 declare function CurrencyDisplay({ value, prefix, showDecimals, textColor, style }: CurrencyDisplayProps): React.JSX.Element;
 
-interface CurrencyInputLargeProps {
-    value?: string;
-    onChangeText?: (formatted: string) => void;
-    /** Called with the parsed numeric value (no separators, no prefix). */
-    onChangeValue?: (raw: number) => void;
-    /** Symbol prepended to the formatted value. Defaults to `'$'`. */
-    prefix?: string;
-    /** Character used to separate groups of three digits. Defaults to `'.'`. */
-    thousandsSeparator?: '.' | ',';
-    label?: string;
-    /** Red helper text; also changes input border to destructive color. */
-    error?: string;
-    hint?: string;
-    placeholder?: string;
-    editable?: boolean;
-    containerStyle?: ViewStyle;
-}
-declare function CurrencyInputLarge({ value, onChangeText, onChangeValue, prefix, thousandsSeparator, label, error, hint, placeholder, editable, containerStyle, }: CurrencyInputLargeProps): 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;
+    /** 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({ icon, title, subtitle, trailing, onPress, disabled, style }: ListItemProps): React.JSX.Element;
+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;
@@ -451,12 +485,14 @@ interface ChipOption {
 }
 interface ChipGroupProps {
     options: ChipOption[];
-    value?: string | number;
-    onValueChange?: (value: string | number) => void;
+    value?: string | number | (string | number)[];
+    onValueChange?: (value: string | number | (string | number)[]) => void;
+    /** When true, allows selecting multiple chips. `value` and `onValueChange` will use arrays. */
+    multiSelect?: boolean;
     style?: ViewStyle;
 }
 declare function Chip({ label, selected, onPress, style }: ChipProps): React.JSX.Element;
-declare function ChipGroup({ options, value, onValueChange, style }: ChipGroupProps): React.JSX.Element;
+declare function ChipGroup({ options, value, onValueChange, multiSelect, style }: ChipGroupProps): React.JSX.Element;
 
 interface ConfirmDialogProps {
     visible: boolean;
@@ -489,4 +525,4 @@ interface MonthPickerProps {
 }
 declare function MonthPicker({ value, onChange, style }: MonthPickerProps): React.JSX.Element;
 
-export { Accordion, type AccordionItem, type AccordionProps, AlertBanner, type AlertBannerProps, type AlertBannerVariant, Avatar, type AvatarProps, type AvatarSize, 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, Checkbox, type CheckboxProps, Chip, ChipGroup, type ChipGroupProps, type ChipOption, type ChipProps, type ColorScheme, ConfirmDialog, type ConfirmDialogProps, CurrencyDisplay, type CurrencyDisplayProps, CurrencyInput, CurrencyInputLarge, type CurrencyInputLargeProps, type CurrencyInputProps, EmptyState, type EmptyStateProps, Input, type InputProps, LabelValue, type LabelValueProps, ListItem, type ListItemProps, MonthPicker, type MonthPickerProps, type MonthPickerValue, Progress, type ProgressProps, RadioGroup, type RadioGroupProps, type RadioOption, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, type SpinnerSize, Switch, type SwitchProps, 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, defaultDark, defaultLight, useTheme, useToast };
+export { Accordion, type AccordionItem, type AccordionProps, AlertBanner, type AlertBannerProps, type AlertBannerVariant, Avatar, type AvatarProps, type AvatarSize, 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, 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, Input, type InputProps, LabelValue, type LabelValueProps, ListItem, type ListItemProps, MonthPicker, type MonthPickerProps, type MonthPickerValue, Progress, type ProgressProps, RadioGroup, type RadioGroupProps, type RadioOption, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, type SpinnerSize, Switch, type SwitchProps, 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, defaultDark, defaultLight, useTheme, useToast };