@retray-dev/ui-kit 10.2.0 → 12.1.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v10.2.0)
+# @retray-dev/ui-kit — Component Reference (v12.1.0)
 
 This file is the AI reference for this package. Add all three lines below to your project's `CLAUDE.md` to give Claude full context — components, setup guide, and usage examples:
 
@@ -317,6 +317,24 @@ const resolved = deriveColors(myThemeColors, 'light')
 
 ---
 
+### Color Utilities
+
+**Import:** `import { withAlpha } from '@retray-dev/ui-kit'`
+
+Convert a hex color to rgba with the given alpha. Useful for semi-transparent backgrounds, borders, and overlays derived from theme colors.
+
+```tsx
+import { useTheme, withAlpha } from '@retray-dev/ui-kit'
+
+const { colors } = useTheme()
+
+<View style={{ backgroundColor: withAlpha(colors.primary, 0.15) }}>
+  <Text style={{ color: colors.primary }}>Tinted background</Text>
+</View>
+```
+
+---
+
 ## Design Tokens
 
 Static structural constants — no context or provider needed.
@@ -684,6 +702,132 @@ assets/fonts/sohne/
 
 ---
 
+## Migration Guide: v10 → v11
+
+### New — public utility
+
+**`withAlpha(hex, alpha)`** — hex-to-rgba color helper, now exported from the package root. Useful for semi-transparent overlays derived from theme colors without adding a new token.
+
+```tsx
+import { useTheme, withAlpha } from '@retray-dev/ui-kit'
+
+const { colors } = useTheme()
+<View style={{ backgroundColor: withAlpha(colors.primary, 0.15) }} />
+```
+
+### Updated
+
+- `Stats` component promoted from internal/experimental to public (`Stats` + `Stats.Group`).
+- Documentation refreshed for `IconPicker` and `NumberStepper`.
+
+No breaking changes in v11. Safe minor upgrade from v10.
+
+---
+
+## Migration Guide: v11 → v12
+
+### Breaking Changes
+
+`Sheet` and `ConfirmDialog` were rewritten on top of `@gorhom/bottom-sheet`'s **`BottomSheetModal`** (lazy-mounted, `present()` / `dismiss()` driven) — replacing the old `BottomSheet` + `index={-1}` + `snapToIndex(0)` pattern. This fixes timing issues with `enableDynamicSizing` and unifies the API with the rest of the gorhom ecosystem.
+
+**1. Removed `responsive` / `dialogMaxWidth` props from `Sheet` and `ConfirmDialog`**
+
+The previous wide-screen fallback that bypassed gorhom with a native `Modal` + `ScrollView` was a partial workaround (see REGLA 1). It has been deleted. `@gorhom/bottom-sheet` handles responsive behavior natively — the modal simply renders inside its modal layer at the device width.
+
+```diff
+ <Sheet
+   open={open}
+   onClose={() => setOpen(false)}
+   title="Options"
+-  responsive
+-  dialogMaxWidth={600}
+ />
+```
+
+**2. `onClose` is the only close handler**
+
+`onClose` is called from `BottomSheetModal.onDismiss` — the native gorhom callback. The previous `onClose` prop (passed directly to `BottomSheet`) was redundant. No public-API change for consumers; this is an internal alignment.
+
+**3. `Sheet` requires `BottomSheetModalProvider` at app root**
+
+`RetrayProvider` already wires it. If you assemble providers manually, ensure `BottomSheetModalProvider` sits inside `GestureHandlerRootView`:
+
+```tsx
+<SafeAreaProvider initialMetrics={initialWindowMetrics}>
+  <GestureHandlerRootView style={{ flex: 1 }}>
+    <ThemeProvider>
+      <BottomSheetModalProvider>
+        <ToastProvider>{/* app */}</ToastProvider>
+      </BottomSheetModalProvider>
+    </ThemeProvider>
+  </GestureHandlerRootView>
+</SafeAreaProvider>
+```
+
+**4. Keyboard prop renames (no consumer action — defaults match v11)**
+
+| Prop | v11 | v12 default |
+|------|-----|-------------|
+| `keyboardBehavior` | `'interactive'` | `'interactive'` (unchanged) |
+| `android_keyboardInputMode` | `'adjustPan'` | `'adjustPan'` (unchanged) |
+
+**5. Removed top-level imports of `Modal`, `ScrollView`, `useWindowDimensions`, `BREAKPOINTS` from `Sheet.tsx`**
+
+Internal only — no public API.
+
+### Behavioral changes (no code change required)
+
+- **Backdrop / swipe close is now driven by gorhom's modal lifecycle** — `onClose` fires once on full dismiss instead of on every interaction. State-setter closures (e.g. `setOpen(false)`) are safe to call from `onClose` without causing "dismiss on unmounted" loops.
+- **`topInset={insets.top}`** is now applied automatically from safe-area context — sheet never crosses the notch / status bar on iOS or Android.
+- **`snapPoints` + `enableDynamicSizing` are mutually exclusive.** If you pass `snapPoints`, dynamic sizing is disabled and the sheet snaps to those points. Omit `snapPoints` to use dynamic sizing (default).
+
+### New — recommended pattern
+
+**Use `Input` with `sheetMode` inside a Sheet** instead of `SheetTextInput` directly. The new `sheetMode` prop on `Input` swaps in `BottomSheetTextInput` for keyboard-aware focus/blur handling while preserving the full `Input` API (label, error, hint, prefix/suffix, icons, type="password").
+
+```tsx
+<Sheet open={open} onClose={() => setOpen(false)} title="Add note">
+  <Input
+    label="Note"
+    placeholder="Type your note..."
+    value={note}
+    onChangeText={setNote}
+    sheetMode
+  />
+  <Button label="Save" fullWidth onPress={handleSave} />
+</Sheet>
+```
+
+`SheetTextInput` is still re-exported for low-level use.
+
+---
+
+## Migration Guide: v12.0 → v12.1
+
+### New — IconPicker feedback pattern (REGLA 4)
+
+`IconPicker` now follows the "no frozen screen" rule. When the user taps the trigger, the sheet presents **immediately** (no `useEffect` delay). While the inner grid measures its container, a centered `<Spinner />` is shown inside the sheet so the user sees visible feedback. The grid fades in as soon as `onLayout` fires.
+
+This is now the canonical pattern for any sheet whose content needs to measure or load before rendering — apply it to new overlay components.
+
+### New — race-condition fix in `Sheet` and `ConfirmDialog`
+
+Both components now track a `wasOpened` ref so `dismiss()` is only called after the sheet has been presented at least once. This eliminates a class of crashes that occurred when the parent component unmounted (or the `open`/`visible` prop flipped) before the gorham modal had a chance to mount.
+
+No consumer action required — the fix is internal.
+
+### New — expanded curated icon library
+
+`src/utils/curatedIcons.ts` has been expanded: every category now carries 42+ icons (some up to 66), totaling ~600 themed icons across the 12 categories. Selection rules are now codified in REGLA 5 — only Feather, Ionicons `-outline`, and themed FA5/Entypo/AntDesign icons are eligible (no filled variants).
+
+### Updated
+
+- `Sheet` and `ConfirmDialog` pass a stable `name` prop to `BottomSheetModal` (from `useId()`) for correct gorhom modal registry behavior when multiple modals are mounted.
+- `Input` `sheetMode` prop documented in the Setup section (replaces the `SheetTextInput` boilerplate inside sheets).
+- `CompositionScreen` example now uses `<Input sheetMode />` inside a `Sheet` to demonstrate the keyboard-friendly pattern.
+
+---
+
 ## Components
 
 ---
@@ -700,6 +844,7 @@ assets/fonts/sohne/
 |------|------|---------|-------|
 | variant | `TextVariant` | `'body-md'` | Sets font, size, weight, line height, letter spacing |
 | color | `string` | — | Override text color. Each variant has a semantic default (see table below) |
+| uppercase | `boolean` | `false` | Force text-transform: uppercase on any variant |
 | children | `ReactNode` | required | — |
 | style | `TextStyle` | — | Additional styles (merged after variant styles) |
 | (all TextProps) | — | — | `numberOfLines`, `ellipsizeMode`, `onPress`, etc. all pass through |
@@ -1073,6 +1218,23 @@ assets/fonts/sohne/
 </View>
 ```
 
+**Composition — inside a Sheet (preferred pattern, v12+):**
+
+Use `sheetMode` to opt the inner `TextInput` into `BottomSheetTextInput` so keyboard handling works correctly. This is the canonical replacement for raw `SheetTextInput` inside sheets.
+
+```tsx
+<Sheet open={open} onClose={() => setOpen(false)} title="Add note">
+  <Input
+    label="Note"
+    placeholder="Write your note..."
+    value={note}
+    onChangeText={setNote}
+    sheetMode
+  />
+  <Button label="Save" fullWidth onPress={handleSave} />
+</Sheet>
+```
+
 ---
 
 ### Textarea
@@ -1125,9 +1287,12 @@ assets/fonts/sohne/
 | hint | `string` | — | Helper text below (hidden when `error` is set) |
 | placeholder | `string` | `'$0'` | Defaults to `prefix + '0'` |
 | editable | `boolean` | — | Pass `false` to disable |
+| autoFocus | `boolean` | — | Auto-focus on mount (inherited from TextInputProps) |
 | containerStyle | `ViewStyle` | — | Outer container style |
 | sheetMode | `boolean` | `false` | Use inside a Sheet — forwards `sheetMode` to underlying `Input` |
 
+**Extends `TextInputProps` from React Native** — all TextInput props (autoFocus, onFocus, onBlur, etc.) pass through to the underlying input.
+
 **Formatting behavior:** Strips all non-digit characters from input, then re-applies thousands separator every 3 digits from the right, then prepends `prefix`. Decimal point input is not supported — this is for whole-number monetary amounts.
 
 **Examples:**
@@ -2400,7 +2565,6 @@ Add `react-native-worklets/plugin` (not `react-native-reanimated/plugin`) to `ba
 | onClose | `() => void` | required | Called on swipe-dismiss or backdrop press |
 | title | `string` | — | Sheet heading |
 | subtitle | `string` | — | Supporting text below title |
-| description | `string` | — | **Deprecated alias** for `subtitle` — prefer `subtitle` |
 | showCloseButton | `boolean` | `false` | Show X close button in the header |
 | children | `ReactNode` | — | Sheet content |
 | style | `ViewStyle` | — | Inner scroll/content container style |
@@ -2413,14 +2577,11 @@ Add `react-native-worklets/plugin` (not `react-native-reanimated/plugin`) to `ba
 | 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) |
-| responsive | `boolean` | `false` | **(v8)** On wide screens (width ≥ `BREAKPOINTS.wide`) render a centered modal dialog instead of a bottom sheet. Stays a bottom sheet on phones |
-| dialogMaxWidth | `number` | `480` | Max width of the centered dialog. Only applies when `responsive` |
 
 **Features:**
 - `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
-- `responsive` — on tablets/web, becomes a centered dialog (max width `dialogMaxWidth`). Note: the dialog path uses a plain RN `Modal`, so `SheetTextInput` is **not** required there — use a regular `TextInput`
-- `enablePanDownToClose` — swipe down to dismiss
+- `enablePanDownToClose` — swipe down to dismiss (always enabled)
 - Backdrop press dismisses
 - **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:
@@ -2429,7 +2590,7 @@ Add `react-native-worklets/plugin` (not `react-native-reanimated/plugin`) to `ba
   - `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
+- **Text inputs inside sheet:** use `<Input sheetMode />` — it transparently swaps in `BottomSheetTextInput` for keyboard-aware focus/blur handling, while preserving the full `Input` API (label, error, hint, prefix/suffix, icons, type="password"). For low-level access, `SheetTextInput` (re-exported `BottomSheetTextInput`) is also available. **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.
@@ -2448,23 +2609,39 @@ const [open, setOpen] = useState(false)
   {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)} 
+// With text input — recommended pattern (v12+): Input sheetMode
+<Sheet
+  open={open}
+  onClose={() => setOpen(false)}
+  title="Add note"
+  subtitle="Keyboard handling is automatic with platform-optimized defaults"
+>
+  <Input
+    label="Note"
+    placeholder="Write your note..."
+    value={note}
+    onChangeText={setNote}
+    sheetMode
+  />
+  <Button label="Save" fullWidth onPress={handleSave} />
+</Sheet>
+
+// Low-level alternative: SheetTextInput
+<Sheet
+  open={open}
+  onClose={() => setOpen(false)}
   title="Add note"
-  subtitle="Keyboard handling is automatic with platform-optimized defaults" 
 >
-  <SheetTextInput 
-    placeholder="Write your note..." 
+  <SheetTextInput
+    placeholder="Write your note..."
     multiline
-    style={{ 
-      borderWidth: 1, 
+    style={{
+      borderWidth: 1,
       borderColor: '#ddd',
       borderRadius: 8,
       padding: 12,
       minHeight: 80,
-    }} 
+    }}
   />
   <Button label="Save" fullWidth style={{ marginTop: 12 }} onPress={() => setOpen(false)} />
 </Sheet>
@@ -2493,7 +2670,7 @@ const [open, setOpen] = useState(false)
 
 **Keyboard handling notes:**
 - No `KeyboardAvoidingView` needed — `@gorhom/bottom-sheet` handles everything
-- Always use `SheetTextInput` (not plain `TextInput`) for auto-focus/blur handling
+- Use `<Input sheetMode />` (preferred) or `SheetTextInput` (low-level) for text inputs inside the sheet
 - 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
@@ -2757,7 +2934,6 @@ dismiss(id)
 | visible | `boolean` | required | Controls dialog visibility |
 | title | `string` | required | Dialog heading |
 | subtitle | `string` | — | Secondary text below title |
-| description | `string` | — | **Deprecated** — use `subtitle` instead |
 | confirmLabel | `string` | `'Confirm'` | Confirm button text |
 | cancelLabel | `string` | `'Cancel'` | Cancel button text |
 | confirmVariant | `'primary' \| 'destructive'` | `'primary'` | Use `'destructive'` for delete/remove actions |
@@ -2767,12 +2943,15 @@ dismiss(id)
 | onCancel | `() => void` | required | Called when cancel is tapped or backdrop pressed |
 
 **Notes:**
-- Powered by `@gorhom/bottom-sheet` with `enableDynamicSizing`
+- Powered by `@gorhom/bottom-sheet` `BottomSheetModal` with `enableDynamicSizing` (v12 refactor — `present()` / `dismiss()` driven, lazy-mounted, no `index={-1}` + `snapToIndex(0)` timing traps)
+- `topInset={insets.top}` applied automatically — dialog never crosses the notch / status bar
+- Internal `wasOpened` ref prevents `dismiss()` being called before the sheet is mounted (race-condition fix from v12.1)
+- A stable `name` prop (from `useId()`) is passed to `BottomSheetModal` for correct gorhom modal registry behavior when multiple modals are open
 - Buttons are full-width, stacked vertically (confirm on top)
 - Cancel shows X icon, confirm shows check (primary) or trash-2 (destructive) icon
 - Swipe down or backdrop press calls `onCancel`
 
-**Haptics:** `impactLight` on open.
+**Haptics:** `impactMedium` on open.
 
 **Examples:**
 ```tsx
@@ -2780,7 +2959,7 @@ dismiss(id)
 <ConfirmDialog
   visible={showDelete}
   title="Delete transaction?"
-  description="$45.000 · Mercado · 12 mar · This action cannot be undone."
+  subtitle="$45.000 · Mercado · 12 mar · This action cannot be undone."
   confirmLabel="Delete"
   confirmVariant="destructive"
   onConfirm={handleDelete}
@@ -2791,7 +2970,7 @@ dismiss(id)
 <ConfirmDialog
   visible={showConfirm}
   title="Send payment?"
-  description={`Send $${amount} to ${recipientName}`}
+  subtitle={`Send $${amount} to ${recipientName}`}
   confirmLabel="Send"
   onConfirm={handleSend}
   onCancel={() => setShowConfirm(false)}
@@ -2801,7 +2980,7 @@ dismiss(id)
 <ConfirmDialog
   visible={showDiscard}
   title="Discard changes?"
-  description="All unsaved changes will be lost."
+  subtitle="All unsaved changes will be lost."
   confirmLabel="Discard"
   confirmVariant="destructive"
   onConfirm={() => { setShowDiscard(false); goBack() }}
@@ -2832,7 +3011,7 @@ dismiss(id)
 | leftIconColor | `string` | — | Override left icon color (default: `foreground`) |
 | rightIconColor | `string` | — | Override right icon color (default: `foregroundMuted`) |
 | variant | `'plain' \| 'card'` | `'plain'` | `plain`: no background. `card`: surface with border and shadow |
-| showChevron | `boolean` | `false` | Right-pointing chevron. Ignored when `rightRender` is set |
+| showChevron | `boolean` | `false` | Right-pointing chevron. Ignored when `rightActions`, `rightRender`, or `rightIcon` is set |
 | showSeparator | `boolean` | `false` | Hairline separator at bottom. Useful for stacking plain items |
 | onPress | `() => void` | — | Makes row pressable (scale animation + haptics) |
 | disabled | `boolean` | — | Reduces opacity to 0.45 |
@@ -2841,13 +3020,12 @@ dismiss(id)
 | subtitleStyle | `TextStyle` | — | Override subtitle text style |
 | subtitleNumberOfLines | `number` | `2` | Max lines for subtitle before truncation |
 | captionStyle | `TextStyle` | — | Override caption text style |
-| icon | `ReactNode` | — | **Deprecated** — use `leftRender` |
-| trailing | `string \| ReactNode` | — | **Deprecated** — use `rightRender` |
+| rightActions | `ReactNode[]` | — | Multiple action buttons on the right with 8pt gap. Takes precedence over `rightRender` |
 
 **Slots:**
 - `leftRender` / `leftIcon` — 44×44pt fixed container, centered. Good for Avatar, icons, thumbnails
 - `rightRender` / `rightIcon` — max 160pt wide, right-aligned. Good for Badge, price text, Switch
-- `showChevron` — `›` chevron, 24pt, `foregroundMuted` color. Only shows when `rightRender` is absent
+- `showChevron` — `›` chevron, 24pt, `foregroundMuted` color. Only shows when `rightRender`, `rightActions`, and `rightIcon` are absent
 
 **Separator inset:** Aligns to text block — `marginLeft` adjusts to skip over left slot when present.
 
@@ -3465,22 +3643,22 @@ const [period, setPeriod] = useState({
 
 **When to use:** Custom interactive content that needs beautiful spring bounce effect matching MediaCard. Use when you need a pressable wrapper around custom layouts that aren't covered by existing button components.
 
-**Extends:** `TouchableOpacityProps` (all native props pass through except `activeOpacity`)
-
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | children | `ReactNode` | required | Content to render inside the pressable |
 | onPress | `() => void` | — | Press handler |
 | pressScale | `number` | `0.98` | Scale value on press (MediaCard-style) |
-| bounciness | `number` | `4` | Spring bounciness on release |
 | haptics | `boolean` | `true` | Enable haptic feedback on press |
 | hoverScale | `number` | `1.02` | Hover scale (web only). Set to `1` to disable |
 | disabled | `boolean` | `false` | Disable interaction |
+| accessibilityRole | `AccessibilityRole` | `'button'` | Override the accessibility role for screen readers |
+| accessibilityState | `Record<string, unknown>` | `{ disabled: !!disabled }` | Accessibility state for selected/expanded/checked |
+| accessibilityLabel | `string` | — | Accessibility label for screen readers |
 | style | `ViewStyle` | — | Animated wrapper style |
 
 **Behavior:**
 - Press: springs to `pressScale` (default 0.98) with `speed: 40, bounciness: 0`
-- Release: springs back to 1.0 with `speed: 40, bounciness: 4`
+- Release: springs back to 1.0 with `speed: 40`
 - Web: optional hover scale (default 1.02)
 - Haptics: `impactLight` on press (unless `haptics={false}`)
 
@@ -3499,7 +3677,7 @@ const [period, setPeriod] = useState({
 </Pressable>
 
 // Wrapping complex layout
-<Pressable onPress={handleSelect} pressScale={0.96} bounciness={8}>
+<Pressable onPress={handleSelect} pressScale={0.96}>
   <View style={{ flexDirection: 'row', alignItems: 'center', gap: 12, padding: 16 }}>
     <Avatar src={user.avatar} size="md" />
     <View style={{ flex: 1 }}>
@@ -3516,7 +3694,7 @@ const [period, setPeriod] = useState({
 </Pressable>
 
 // Custom press scale (deeper press)
-<Pressable onPress={handlePress} pressScale={0.92} bounciness={6}>
+<Pressable onPress={handlePress} pressScale={0.92}>
   {/* content */}
 </Pressable>
 ```
@@ -3788,6 +3966,76 @@ export default function TabLayout() {
 
 ---
 
+### Stats
+
+**Import:** `import { Stats } from '@retray-dev/ui-kit'`
+
+**When to use:** Dashboards and analytics screens — single-stat card with a large value, icon, label, and optional description. Tappable cards wire haptics automatically.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| value | `string` | required | Large display value, e.g. `"$12,450"` or `"847"` |
+| label | `string` | required | Label below the value, e.g. `"Monthly Revenue"` |
+| description | `string` | — | Third line — smaller, muted text for trend/context |
+| icon | `React.ReactNode` | — | Custom icon node |
+| iconName | `string` | — | Icon from `@expo/vector-icons` (left of value, `colors.primary`) |
+| iconColor | `string` | `colors.primary` | Override icon color |
+| variant | `'elevated' \| 'outlined' \| 'filled'` | `'elevated'` | Card surface variant |
+| onPress | `() => void` | — | Makes the card pressable (haptic `impactLight()`) |
+| style | `ViewStyle` | — | — |
+| accessibilityLabel | `string` | — | — |
+
+**Design notes:** Value uses `Sohne-Bold` at 28px. Label uses `Sohne-Regular` at 13px in `foregroundSubtle`. Description uses `Sohne-Regular` at 12px in `foregroundMuted`. Icon renders at 22px, left-aligned with the value. All content is centered vertically and horizontally. The card shrinks to fit its content by default (`alignSelf: 'flex-start'`). When placed inside `Stats.Group`, cards stretch to equal width. When the card is narrow (< 150dp) and has an icon, the layout switches to vertical stacking (icon → value → label → description) to avoid overflow.
+
+**`Stats.Group`** — horizontal layout wrapper that distributes children equally:
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `React.ReactNode` | required | `Stats` components to arrange horizontally |
+| gap | `number` | `s(12)` | Spacing between cards |
+| style | `ViewStyle` | — | — |
+
+**Layout guidance:** Prefer 2-up for values longer than ~3 digits (e.g. `"$12,450"`, `"1,234"`) or with descriptions. Use 3-up only for very compact metrics with short values (e.g. `"847"`, `"98%"`) and no description — otherwise values will wrap and look broken.
+
+**Example:**
+```tsx
+// Standalone
+<Stats
+  value="$12,450"
+  label="Monthly Revenue"
+  description="+12% from last month"
+  iconName="trending-up"
+/>
+
+// 3-up — short values only, no description
+<Stats.Group>
+  <Stats value="847" label="Users" variant="elevated" />
+  <Stats value="98%" label="Uptime" variant="outlined" />
+  <Stats value="12" label="Alerts" variant="filled" />
+</Stats.Group>
+
+// 2-up with icons, long values, and description
+<Stats.Group gap={s(16)}>
+  <Stats
+    value="$8,200"
+    label="Spent"
+    description="This month"
+    iconName="credit-card"
+    variant="elevated"
+    onPress={() => navigateToBilling()}
+  />
+  <Stats
+    value="$2,150"
+    label="Saved"
+    description="12% of budget"
+    iconName="trending-up"
+    variant="outlined"
+  />
+</Stats.Group>
+```
+
+---
+
 ### ErrorBoundary
 
 **Import:** `import { ErrorBoundary } from '@retray-dev/ui-kit'`
@@ -4030,7 +4278,7 @@ const handleChange = async (uri: string | null) => {
 
 **Import:** `import { IconPicker } from '@retray-dev/ui-kit'`
 
-**When to use:** Selecting an icon from a curated catalog of ~320 icons (across all 6 `@expo/vector-icons` families) organized by 12 categories. The trigger is a simple tappable square showing the selected icon (or a + placeholder). Tapping opens a bottom sheet with category chips (icon + label) and a scrollable grid. No search, no text clutter — purely visual selection.
+**When to use:** Selecting an icon from a curated catalog of ~600 themed icons (across Feather, Ionicons `-outline`, FA5 Brands/regular, Entypo, AntDesign — only outlined variants) organized by 12 categories. The trigger is a simple tappable square showing the selected icon (or a + placeholder). Tapping opens a bottom sheet with category chips (icon + label) and a scrollable grid. No search, no text clutter — purely visual selection.
 
 **Requires:** `@gorhom/bottom-sheet` (already a peer dependency of the UI kit).
 
@@ -4067,10 +4315,12 @@ const [icon, setIcon] = useState<string | null>(null)
 ```
 
 **Notes:**
-- Uses a static curated list of ~320 icons in 12 categories (food, sports, business, objects, status, actions, communication, navigation, media, layout, nature, brands) — instant load, no runtime glyphMap scanning.
+- Uses a static curated list of ~600 outlined icons in 12 categories (food, sports, business, objects, status, actions, communication, navigation, media, layout, nature, brands), with at least 42 icons per category — instant load, no runtime glyphMap scanning.
+- Icon selection rules are strict: only Feather, Ionicons `-outline`, and themed FA5/Entypo/AntDesign icons are eligible. Filled variants and FA5-only-solid icons are excluded to keep the visual style consistent. See `src/utils/curatedIcons.ts` for the source of truth.
+- **Feedback pattern (v12.1):** the sheet presents **immediately** on trigger tap (no `useEffect` delay). While the grid container measures its width via `onLayout`, a centered `<Spinner />` is shown inside the sheet so the user always sees visible feedback. The grid transitions in as soon as measurement is complete. This is the canonical REGLA 4 pattern — apply it to any overlay whose content needs to measure before rendering.
 - Category chips use representative icons (coffee, activity, briefcase, folder, alert-circle, edit-3, message-circle, compass, image, grid, sun, globe) with Spanish labels and a "Todos" (All) chip.
 - Grid cells show only icons — clean, fast visual scanning. Cell size adapts to container width.
-- Sheet uses `enableDynamicSizing` with `maxDynamicContentSize` (70% screen height) — height auto-fits content up to that cap.
+- Sheet uses `enableDynamicSizing` with `maxDynamicContentSize` (70% screen height) — height auto-fits content up to that cap. `topInset={insets.top}` is applied automatically.
 - Category strip is a horizontal `ScrollView` of pill-shaped chips. The grid is rendered in rows inside a `BottomSheetScrollView`.
 - Selection closes the sheet immediately and resets category to "Todos".
 - Haptics: medium impact on open, selection on icon tap.

package/README.md

@@ -2,7 +2,7 @@
 
 A personal React Native / Expo UI component library with a built-in design system, dark mode support, haptic feedback, and smooth animations.
 
-- 53 components across 9 categories (plus the deep-import `HolographicCard`)
+- 54 components across 9 categories (plus the deep-import `HolographicCard`)
 - Light/dark theme with 12 public tokens (25 resolved) and full customization
 - Apple HIG–compliant touch targets and haptic feedback
 - Animated interactions: spring press, sliding tabs, accordion easing, animated progress
@@ -177,11 +177,15 @@ import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS, TYPOGRAPHY } from '@
 | `BREAKPOINTS` | `wide` (700) |
 | `TYPOGRAPHY` | 16 variants: `display-hero`, `display-xl`, `display-lg`, `display-md`, `display-sm`, `title-md`, `title-sm`, `body-md`, `body-sm`, `caption`, `caption-sm`, `badge-text`, `micro-label`, `uppercase-tag`, `button-lg`, `button-sm` |
 
+### Color Utilities
+
+- **`withAlpha(color: string, alpha: number)`** — takes a hex color string (e.g., `"#6366f1"`) and an opacity value (0–1), returns an `rgba()` string. Useful for semi-transparent overlays without adding a separate token.
+
 ## Components
 
 | Category    | Components                                                                                      |
 | ----------- | ----------------------------------------------------------------------------------------------- |
-| Display     | `Text`, `Badge`, `Avatar`, `Separator`, `Spinner`, `Skeleton`, `Progress`, `CurrencyDisplay`   |
+| Display     | `Text`, `Badge`, `Avatar`, `Separator`, `Spinner`, `Skeleton`, `Progress`, `CurrencyDisplay`, `Stats` |
 | Surfaces    | `Card`, `AlertBanner`, `EmptyState`, `MediaCard`, `PricingCard`                                 |
 | Form        | `Form` (+ `Form.Field` / `Form.Section` / `Form.Footer`), `Button`, `ButtonGroup`, `IconButton`, `Input`, `CurrencyInput`, `Textarea`, `Checkbox`, `Switch`, `Toggle`, `RadioGroup`, `Select`, `Slider`, `SelectableGrid`, `SheetSelect`, `ImageUpload`, `IconPicker`, `NumberStepper` |
 | Composition | `Tabs`, `Accordion`                                                                             |
@@ -220,6 +224,11 @@ toast({ title: 'Saved', variant: 'success' })
   options={[{ label: 'Option A', value: 'a' }, { label: 'Option B', value: 'b' }]}
   placeholder="Pick one"
 />
+
+// Color utilities
+import { useTheme, withAlpha } from '@retray-dev/ui-kit'
+const { colors } = useTheme()
+;<View style={{ backgroundColor: withAlpha(colors.primary, 0.15) }} />
 ```
 
 Full props reference and more examples are available in [COMPONENTS.md](./COMPONENTS.md), which is also shipped inside the npm package for use with AI tools:

package/dist/Accordion.mjs

@@ -1,7 +1,7 @@
-export { Accordion } from './chunk-YJ7I257J.mjs';
+export { Accordion } from './chunk-265G6A46.mjs';
 import './chunk-EJ7ZPXOH.mjs';
 import './chunk-DVK4G2GT.mjs';
 import './chunk-KA7LTET3.mjs';
-import './chunk-SOYNZDVY.mjs';
+import './chunk-EMUWGDWC.mjs';
 import './chunk-2CE3TQVY.mjs';
 import './chunk-Y6FXYEAI.mjs';

package/dist/AlertBanner.mjs

@@ -1,6 +1,6 @@
-export { AlertBanner } from './chunk-BEMIQXXU.mjs';
+export { AlertBanner } from './chunk-V6NFJXKO.mjs';
 import './chunk-QY3X2UYR.mjs';
 import './chunk-KA7LTET3.mjs';
-import './chunk-SOYNZDVY.mjs';
+import './chunk-EMUWGDWC.mjs';
 import './chunk-2CE3TQVY.mjs';
 import './chunk-Y6FXYEAI.mjs';

package/dist/AppHeader.mjs

@@ -1,10 +1,10 @@
-export { AppHeader } from './chunk-TBNZHU6C.mjs';
-import './chunk-T2KCAHOS.mjs';
+export { AppHeader } from './chunk-ISY26JQJ.mjs';
+import './chunk-DF6DU42P.mjs';
 import './chunk-3DKJ2GIC.mjs';
 import './chunk-EJ7ZPXOH.mjs';
 import './chunk-DVK4G2GT.mjs';
 import './chunk-QY3X2UYR.mjs';
 import './chunk-KA7LTET3.mjs';
-import './chunk-SOYNZDVY.mjs';
+import './chunk-EMUWGDWC.mjs';
 import './chunk-2CE3TQVY.mjs';
 import './chunk-Y6FXYEAI.mjs';

package/dist/Avatar.mjs

@@ -1,4 +1,4 @@
-export { Avatar } from './chunk-JT7HKXRB.mjs';
-import './chunk-SOYNZDVY.mjs';
+export { Avatar } from './chunk-S3KJCPEJ.mjs';
+import './chunk-EMUWGDWC.mjs';
 import './chunk-2CE3TQVY.mjs';
 import './chunk-Y6FXYEAI.mjs';

package/dist/Badge.mjs

@@ -1,5 +1,5 @@
-export { Badge } from './chunk-VF2ATYN3.mjs';
+export { Badge } from './chunk-3UYAZ7I4.mjs';
 import './chunk-KA7LTET3.mjs';
-import './chunk-SOYNZDVY.mjs';
+import './chunk-EMUWGDWC.mjs';
 import './chunk-2CE3TQVY.mjs';
 import './chunk-Y6FXYEAI.mjs';

package/dist/Button.mjs

@@ -1,9 +1,9 @@
-export { Button } from './chunk-HTHGSXFG.mjs';
+export { Button } from './chunk-DOGIPOF5.mjs';
 import './chunk-3DKJ2GIC.mjs';
 import './chunk-EJ7ZPXOH.mjs';
 import './chunk-DVK4G2GT.mjs';
 import './chunk-QY3X2UYR.mjs';
 import './chunk-KA7LTET3.mjs';
-import './chunk-SOYNZDVY.mjs';
+import './chunk-EMUWGDWC.mjs';
 import './chunk-2CE3TQVY.mjs';
 import './chunk-Y6FXYEAI.mjs';

package/dist/Card.mjs

@@ -1,8 +1,8 @@
-export { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from './chunk-ID72TK46.mjs';
+export { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from './chunk-2CBQKU7H.mjs';
 import './chunk-3DKJ2GIC.mjs';
 import './chunk-EJ7ZPXOH.mjs';
 import './chunk-DVK4G2GT.mjs';
 import './chunk-QY3X2UYR.mjs';
-import './chunk-SOYNZDVY.mjs';
+import './chunk-EMUWGDWC.mjs';
 import './chunk-2CE3TQVY.mjs';
 import './chunk-Y6FXYEAI.mjs';

package/dist/CategoryStrip.mjs

@@ -1,9 +1,9 @@
-export { CategoryStrip } from './chunk-6L4G6PBT.mjs';
+export { CategoryStrip } from './chunk-MYZ2EDYU.mjs';
 import './chunk-YNROWHQJ.mjs';
 import './chunk-EJ7ZPXOH.mjs';
 import './chunk-DVK4G2GT.mjs';
 import './chunk-QY3X2UYR.mjs';
 import './chunk-KA7LTET3.mjs';
-import './chunk-SOYNZDVY.mjs';
+import './chunk-EMUWGDWC.mjs';
 import './chunk-2CE3TQVY.mjs';
 import './chunk-Y6FXYEAI.mjs';