@retray-dev/ui-kit 10.1.0 → 12.1.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v10.1.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:**
@@ -1175,6 +1340,69 @@ const [amount, setAmount] = useState(0)
 
 ---
 
+### NumberStepper
+
+**Import:** `import { NumberStepper } from '@retray-dev/ui-kit'`
+
+**When to use:** Quantity +/- controls — cart item counts, guest selectors, inventory adjustments, portion sizes. Use when the user needs to increment/decrement a discrete numeric value within a constrained range (min–max).
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| value | `number` | required | Current numeric value |
+| onValueChange | `(value: number) => void` | required | Called with clamped value on each step |
+| min | `number` | `1` | Minimum allowed value |
+| max | `number` | `99` | Maximum allowed value |
+| step | `number` | `1` | Increment/decrement amount. Supports decimals (e.g. `0.5`) |
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | Controls button and value text size |
+| disabled | `boolean` | `false` | Disables both buttons |
+| accessibilityLabel | `string` | — | Custom a11y label for value text. Default: `"Quantity: {value}"` |
+| style | `ViewStyle` | — | Outer container style |
+
+**Styling:** Row layout with two square buttons flanking a centered value label. Buttons use `RADIUS.md` (14pt), `borderWidth: 1.5`, `surface` background with `border` outline. Value text: `Sohne-Medium`, centered, `foreground` color.
+
+**Button states:** The decrement button disables (opacity 0.35, non-pressable) when `value ≤ min`. The increment button disables when `value ≥ max`. Both disable when the `disabled` prop is `true`.
+
+**Haptics:** `impactLight` on each press.
+
+**Accessibility:** Each button has a descriptive label (`"Decrease, current value X"` / `"Increase, current value X"`). The value text has `accessibilityRole="text"`. Disabled state passed to `accessibilityState`.
+
+**Animation:** `PressableButton` (scale 0.95) on each button — matches the Button/IconButton press feel.
+
+**Examples:**
+```tsx
+// Basic quantity stepper
+const [qty, setQty] = useState(1)
+<NumberStepper value={qty} onValueChange={setQty} />
+
+// Custom range and step
+const [rating, setRating] = useState(3)
+<NumberStepper value={rating} onValueChange={setRating} min={0} max={5} step={0.5} />
+
+// Large size for prominent use
+const [guests, setGuests] = useState(2)
+<NumberStepper value={guests} onValueChange={setGuests} min={1} max={16} size="lg" />
+
+// Disabled during async operation
+<NumberStepper
+  value={qty}
+  onValueChange={setQty}
+  disabled={isUpdating}
+/>
+```
+
+**Composition — cart item row:**
+```tsx
+<View style={{ flexDirection: 'row', alignItems: 'center', justifyContent: 'space-between' }}>
+  <View>
+    <Text variant="body-md">Margherita Pizza</Text>
+    <Text variant="caption-sm" color={colors.foregroundMuted}>$12.000</Text>
+  </View>
+  <NumberStepper value={quantity} onValueChange={setQuantity} />
+</View>
+```
+
+---
+
 ### CurrencyDisplay
 
 **Import:** `import { CurrencyDisplay } from '@retray-dev/ui-kit'`
@@ -2337,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 |
@@ -2350,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:
@@ -2366,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.
@@ -2385,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>
@@ -2430,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
@@ -2694,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 |
@@ -2704,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
@@ -2717,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}
@@ -2728,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)}
@@ -2738,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() }}
@@ -2769,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 |
@@ -2778,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.
 
@@ -3077,7 +3318,7 @@ dismiss(id)
 
 **Import:** `import { Chip, ChipGroup } from '@retray-dev/ui-kit'`
 
-**When to use:** Inline filter options, quick selections, multi-select toggles. Use `Chip` for standalone custom logic; use `ChipGroup` for managed selection (single or multi).
+**When to use:** Inline filter options, quick selections, multi-select toggles. Use `Chip` for standalone custom logic; use `ChipGroup` for managed selection (single or multi). **ChipGroup vs CategoryStrip:** ChipGroup wraps to multiple rows and supports disabled items — best for filter tags, feature toggles, and tray-style selections. CategoryStrip scrolls horizontally and supports badge counts — best for top-of-screen category browsers.
 
 **`Chip` Props:**
 
@@ -3149,7 +3390,7 @@ const [categories, setCategories] = useState<number[]>([1, 3])
 
 **Import:** `import { CategoryStrip } from '@retray-dev/ui-kit'`
 
-**When to use:** Horizontal scrollable filter/category bar at the top of browse screens — marketplace categories, content type filters, location tabs. Airbnb-style pill chips that scroll horizontally.
+**When to use:** Horizontal scrollable filter/category bar at the top of browse screens — marketplace categories, content type filters, location tabs. Airbnb-style pill chips that scroll horizontally. **CategoryStrip vs ChipGroup:** CategoryStrip scrolls horizontally and supports badge counts — best for top-of-screen category browsers. ChipGroup wraps to multiple rows and supports disabled items — best for filter tags and tray-style selections.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
@@ -3274,7 +3515,7 @@ const [categories, setCategories] = useState<number[]>([1, 3])
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | label | `string \| ReactNode` | required | Left side. Strings auto-styled in `foregroundMuted` caption |
-| value | `string` | required | Right side value text |
+| value | `string \| number \| ReactNode` | required | Right side value. Strings and numbers auto-styled in `Sohne-SemiBold`; pass `ReactNode` for custom content |
 | 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) |
@@ -3402,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}`)
 
@@ -3436,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 }}>
@@ -3453,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>
 ```
@@ -3725,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'`
@@ -3920,6 +4231,7 @@ import { HolographicCard, FOIL_PRESETS } from '@retray-dev/ui-kit/HolographicCar
 | onChange | `(uri: string \| null) => void` | — | Called with selected URI after picker completes |
 | loading | `boolean` | `false` | Show spinner overlay (e.g. while uploading to server) |
 | placeholder | `string` | `'Tap to add image'` | Text shown when no image selected |
+| showPlaceholderText | `boolean` | `true` | Whether to show the placeholder text. Use `false` for compact/avatar variants |
 | width | `number` | — | Width of the upload area. Defaults to full width |
 | height | `number` | `200` | Height of the upload area |
 | borderRadius | `number` | `RADIUS.lg` | — |
@@ -3949,18 +4261,72 @@ const handleChange = async (uri: string | null) => {
   height={200}
 />
 
-// Avatar upload (square)
+// Avatar upload (square, no text)
 <ImageUpload
   value={avatarUri}
   onChange={setAvatarUri}
   width={100}
   height={100}
   borderRadius={50}
+  showPlaceholderText={false}
 />
 ```
 
 ---
 
+### IconPicker
+
+**Import:** `import { IconPicker } from '@retray-dev/ui-kit'`
+
+**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).
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| value | `string \| null` | — | Currently selected icon name |
+| onChange | `(iconName: string) => void` | — | Called when an icon is selected |
+| label | `string` | — | Optional label above the trigger |
+| error | `string` | — | Error message (red border + helper text) |
+| hint | `string` | — | Hint text below trigger |
+| disabled | `boolean` | `false` | Prevents opening |
+| numColumns | `number` | `6` | Icons per row in the sheet grid |
+| gap | `number` | `6` | Gap between cells (dp) |
+| style | `ViewStyle` | — | — |
+
+**Examples:**
+```tsx
+const [icon, setIcon] = useState<string | null>(null)
+
+// Basic usage
+<IconPicker
+  label="Icon"
+  value={icon}
+  onChange={setIcon}
+/>
+
+// With validation error
+<IconPicker
+  label="Icon"
+  value={icon}
+  onChange={setIcon}
+  error={!icon ? 'Please select an icon' : undefined}
+/>
+```
+
+**Notes:**
+- 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. `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.
+
+---
+
 ### useConfirmDialog
 
 **Import:** `import { useConfirmDialog } from '@retray-dev/ui-kit'`
@@ -4063,6 +4429,21 @@ import { renderIcon } from '@retray-dev/ui-kit'
 const icon = renderIcon('check', 18, colors.primary)
 ```
 
+### `getValidIconNames` utility
+
+```tsx
+import { getValidIconNames } from '@retray-dev/ui-kit'
+
+// All icon names across all configured families
+const allIcons: string[] = getValidIconNames()
+// => ["home", "user", "heart", "star", ...]
+
+// Scoped to specific families (does not mutate global config)
+const featherOnly: string[] = getValidIconNames(['Feather'])
+```
+
+Returns `string[]` — all resolvable icon names from the configured families. Respects `configureIconFamilies()` global config. The optional `families` parameter builds a temporary cache scoped to those families without mutating global state. Use to build icon pickers, search, and galleries.
+
 ### `iconName` props on components
 
 All components with icon slots accept `iconName` — auto-resolved size and color: