@retray-dev/ui-kit 10.2.0 → 12.2.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:
 
@@ -275,8 +275,9 @@ The full palette components consume. Never supply these directly — they are co
 |-------|-------------|---------|
 | `foregroundSubtle` | `foreground` @ ~70% | Body text, subtitles, secondary content |
 | `foregroundMuted` | `foreground` @ ~62% | Captions, timestamps, placeholders |
-| `surface` | `background` slightly off-canvas | Chip backgrounds, input fills, tag backgrounds, skeleton |
+| `surface` | `background` slightly off-canvas | Chip backgrounds, input fills, tag backgrounds |
 | `surfaceStrong` | `background` stronger offset | Pressed/hover fill states |
+| `skeleton` | `background` @ ±10% | Skeleton placeholder — higher contrast than surface for visibility |
 | `destructiveTint` | `destructive` blended to bg | Alert banner background, toast background |
 | `destructiveBorder` | `destructive` @ 30% | Alert banner border, badge outline |
 | `successTint` | `success` blended to bg | Success banner background |
@@ -285,6 +286,7 @@ The full palette components consume. Never supply these directly — they are co
 | `warningBorder` | `warning` @ 30% | Warning banner border |
 | `ring` | `= primary` | Focus ring color (always matches primary) |
 | `input` | `= border` | Input field border (always matches border) |
+| `separator` | `border` @ ±16-22% | Divider/separator line — deliberately darker than border |
 | `overlay` | `overlay` token or `rgba(0,0,0,0.45)` | Backdrop behind sheets and dialogs |
 | `accentResolved` | `accent` token or `= primary` | Resolved accent color — always present |
 | `accentForegroundResolved` | `accentForeground` token or `= primaryForeground` | Resolved text on accent — always present |
@@ -312,7 +314,25 @@ const { colors } = useTheme()
 import { deriveColors } from '@retray-dev/ui-kit'
 
 const resolved = deriveColors(myThemeColors, 'light')
-// resolved contains all 24 ResolvedColors tokens
+// resolved contains all 26 ResolvedColors tokens
+```
+
+---
+
+### 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>
 ```
 
 ---
@@ -684,6 +704,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 +846,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 |
@@ -772,7 +919,7 @@ assets/fonts/sohne/
 | size | `'sm' \| 'md' \| 'lg'` | `'md'` | Controls height, padding, and icon size |
 | loading | `boolean` | `false` | Replaces label with spinner, forces disabled state |
 | fullWidth | `boolean` | `false` | Stretches to container width (`alignSelf: 'stretch'`) |
-| disabled | `boolean` | — | Reduces opacity to 0.5 |
+| disabled | `boolean` | — | Per-variant explicit colors (no opacity). `filled`→`surface` bg, `secondary`→`border` border, `text`/`outline`→`foregroundMuted` text |
 | icon | `React.ReactNode \| ((props: { label, size, variant }) => React.ReactNode)` | — | Icon rendered alongside label |
 | iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` |
 | iconColor | `string` | — | Override icon color. Defaults to variant label color |
@@ -1073,6 +1220,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 +1289,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:**
@@ -1737,6 +1904,7 @@ const renderItem = useCallback(({ item }) => (
 | width | `number \| string` | `'100%'` | Width of placeholder |
 | height | `number` | `16` | Height of placeholder |
 | borderRadius | `number` | `6` | Corner radius |
+| backgroundColor | `string` | `colors.skeleton` | Override placeholder background color |
 | preset | `'base' \| 'circle' \| 'text'` | `'base'` | Convenience preset |
 | diameter | `number` | `40` | Used by `'circle'` preset — overrides width/height |
 | style | `ViewStyle` | — | — |
@@ -2184,6 +2352,94 @@ const [accepted, setAccepted] = useState(false)
 
 ---
 
+### SelectableCard
+
+**Import:** `import { SelectableCard, SelectableCardGroup } from '@retray-dev/ui-kit'`
+
+**When to use:** Selectable cards with radio (single-select) or checkbox (multi-select) behavior. Each card supports an icon, title, description, and disabled state. Perfect for role selectors, plan pickers, feature/module configuration — anywhere you need descriptive options that communicate more than a simple label.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| value | `string` | required | The value this card represents |
+| title | `string` | required | Card title |
+| description | `string` | — | Secondary text below title |
+| iconName | `string` | — | Left icon from @expo/vector-icons |
+| icon | `ReactNode` | — | Custom left icon |
+| disabled | `boolean` | `false` | Grayed out, no press/haptic |
+| style | `ViewStyle` | — | — |
+
+**SelectableCardGroup Props:**
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| type | `'radio' \| 'checkbox'` | `'radio'` | Selection mode |
+| value | `string \| string[]` | required | Selected value(s) |
+| onValueChange | `(value: string \| string[]) => void` | required | — |
+| variant | `'elevated' \| 'outlined' \| 'filled'` | `'elevated'` | Card surface |
+| gap | `number` | `s(8)` | Spacing between cards |
+| style | `ViewStyle` | — | — |
+
+**Card variants:** `elevated` (shadow depth, 2px border matches background when unselected — no layout shift on select), `outlined` (2px border), `filled` (surfaceStrong background + 2px border). All variants use a consistent 2px border width so cards don't resize when selected.
+
+**Selection visual:** Selected cards get a 2px `colors.primary` border + `EaseView` animated selector indicator. Radio shows a 24×24 circle with spring-animated inner dot. Checkbox shows a 24×24 box with opacity-animated checkmark. Both follow the same visual patterns as `RadioGroup` and `Checkbox`.
+
+**Haptics:** `impactLight` on selection.
+
+**Disabled:** Dims content to `foregroundMuted`, removes shadow/elevation, keeps border at `colors.border`. No press, no haptic.
+
+**Examples:**
+```tsx
+// Single select (radio)
+<SelectableCardGroup
+  type="radio"
+  value={selectedRole}
+  onValueChange={setSelectedRole}
+>
+  <SelectableCard
+    value="admin"
+    iconName="shield"
+    title="Administrator"
+    description="Full access to reports, settings, and business management"
+  />
+  <SelectableCard
+    value="waiter"
+    iconName="user-check"
+    title="Waiter"
+    description="Take orders from tables and manage requests"
+  />
+  <SelectableCard
+    value="cook"
+    iconName="chef-hat"
+    title="Cook"
+    description="Receive and prepare items from each order in the kitchen"
+    disabled
+  />
+</SelectableCardGroup>
+
+// Multi select (checkbox)
+<SelectableCardGroup
+  type="checkbox"
+  value={selectedRoles}
+  onValueChange={setSelectedRoles}
+  variant="outlined"
+>
+  <SelectableCard
+    value="reports"
+    iconName="bar-chart-2"
+    title="Reports"
+    description="View sales, inventory, and performance analytics"
+  />
+  <SelectableCard
+    value="inventory"
+    iconName="package"
+    title="Inventory"
+    description="Manage stock levels and supplier orders"
+  />
+</SelectableCardGroup>
+```
+
+---
+
 ### Slider
 
 **Import:** `import { Slider } from '@retray-dev/ui-kit'`
@@ -2345,6 +2601,7 @@ const [tab, setTab] = useState('profile')
   iconName?: string          // Icon name from @expo/vector-icons
   icon?: ReactNode           // Custom icon node
   iconColor?: string         // Override icon color (defaults to foregroundMuted)
+  triggerActions?: ReactNode // Action buttons rendered between trigger and chevron. Touch-isolated — taps on actions won't toggle the accordion.
 }
 ```
 
@@ -2400,7 +2657,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 +2669,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 +2682,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 +2701,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 +2762,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 +3026,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 +3035,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 +3051,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 +3062,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 +3072,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 +3103,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 +3112,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 +3735,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 +3769,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 +3786,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 +4058,77 @@ 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 |
+| size | `'default' \| 'compact'` | `'default'` | `compact`: 16px SemiBold value, 11px label, reduced padding |
+| 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 21px. Label uses `Sohne-Regular` at 13px in `foregroundSubtle`. Description uses `Sohne-Regular` at 12px in `foregroundMuted`. Icon renders at 20px, 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'`
@@ -3989,6 +4330,7 @@ import { HolographicCard, FOIL_PRESETS } from '@retray-dev/ui-kit/HolographicCar
 | borderRadius | `number` | `RADIUS.lg` | — |
 | resizeMode | `'cover' \| 'contain' \| 'stretch'` | `'cover'` | Image resize mode |
 | disabled | `boolean` | `false` | Prevents pressing |
+| allowsEditing | `boolean` | `true` | When `true`, iOS opens the crop/editing screen after selecting an image. Set `false` to accept the image directly without cropping |
 | style | `ViewStyle` | — | — |
 | accessibilityLabel | `string` | — | — |
 
@@ -4030,7 +4372,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 +4409,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.