@retray-dev/ui-kit 5.1.0 → 5.4.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v5.0.0)
+# @retray-dev/ui-kit — Component Reference (v5.4.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:
 
@@ -499,6 +499,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 +743,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 +753,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 +840,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 +941,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 +971,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 +1843,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 +1864,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>,
     },
   ]}
@@ -1828,11 +1907,16 @@ Add `react-native-worklets/plugin` (not `react-native-reanimated/plugin`) to `ba
 | description | `string` | — | Supporting text below title |
 | 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` |
 
 **Features:**
 - `enableDynamicSizing` — height auto-fits content, no `snapPoints` needed
 - `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.
 
@@ -1855,6 +1939,18 @@ const [open, setOpen] = useState(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>
+  ))}
+</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} />)}
+</Sheet>
+
 // Filter sheet
 <Sheet open={filterOpen} onClose={() => setFilterOpen(false)} title="Filters">
   <View style={{ gap: SPACING.lg }}>
@@ -2165,7 +2261,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 |
@@ -2310,27 +2406,96 @@ 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}`} 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 />
-  <LabelValue label="Amount" value={`$${transaction.amount}`} />
+  <DetailRow label="Total" value="$50.000" labelWeight="bold" />
 </View>
 ```
 
+**Output:**
+```
+Juliana ············ $25.000
+Julián ············· $25.000
+─────────────────────────────
+Total ·············· $50.000
+```
+
 ---
 
 ### MonthPicker
@@ -2343,6 +2508,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:**
@@ -2366,6 +2533,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>
@@ -2513,6 +2690,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
@@ -2577,3 +2791,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.