@retray-dev/ui-kit 12.1.0 → 13.0.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v12.1.0)
+# @retray-dev/ui-kit — Component Reference (v13.0.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:
 
@@ -99,10 +99,10 @@ module.exports = function (api) {
 | `@expo/vector-icons` | **Required** | Icons everywhere | |
 | `react-native-size-matters` | **Required** | Responsive scaling | |
 | `react-native-ease` | **Required** | `Checkbox`, `Chip`, `CategoryStrip`, `Switch`, `RadioGroup`, `Toggle` | Declarative `EaseView` animation layer. Static import in source — omitting it crashes the module load. `pnpm add react-native-ease` |
-| `react-native-pulsar` | **Optional** | Rich haptics on dev builds | Loaded via dynamic `import()` + try/catch; falls back to `expo-haptics`. Skip in Expo Go. `pnpm add react-native-pulsar` |
+
 | `@shopify/react-native-skia` + `expo-sensors` | **Optional** | Deep-import `HolographicCard` only | `pnpm add @shopify/react-native-skia expo-sensors` |
 
-> **Dev build vs Expo Go:** Everything in the kit runs in **Expo Go** — `react-native-pulsar` is the only native module that needs a custom dev build, and it degrades gracefully (basic haptics) when absent. No component is broken by running in Expo Go.
+
 
 ### Troubleshooting: `react-native-screens` codegen on RN 0.83
 
@@ -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,7 @@ 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
 ```
 
 ---
@@ -917,7 +919,7 @@ No consumer action required — the fix is internal.
 | 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 |
@@ -1559,6 +1561,65 @@ const [guests, setGuests] = useState(2)
 
 ---
 
+### AvatarGroup
+
+**Import:** `import { AvatarGroup } from '@retray-dev/ui-kit'`
+
+**When to use:** Stacked/overlapping avatars to show multiple users in a compact space. Common for collaborator indicators, multi-waiter tables, and team members.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| users | `{ name: string; src?: string }[]` | required | User data — name used for fallback initials |
+| max | `number` | `3` | Max avatars visible before `+N` overflow badge |
+| size | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'sm'` | Avatar size preset, passed to each `Avatar` |
+| overlap | `number` | `vs(8)` | Overlap in points between consecutive avatars |
+| onOverflowPress | `() => void` | — | Tap handler for the `+N` overflow badge |
+| style | `ViewStyle` | — | Outer container style |
+
+**Sizes:** Same as `Avatar` — `sm` (28px), `md` (40px), `lg` (56px), `xl` (72px).
+
+**Notes:**
+- Overflow badge uses `surfaceStrong` background with `foregroundMuted` text.
+- Individual avatars are not tappable — only the `+N` badge fires `onOverflowPress`.
+- `overlap` follows the spacing grid (defaults to `spacing.sm` = 8pt).
+
+**Examples:**
+```tsx
+// Basic — 5 waiters, show max 3
+<AvatarGroup
+  users={[
+    { name: 'Ana', src: 'https://...' },
+    { name: 'Bob', src: 'https://...' },
+    { name: 'Carlos' },
+    { name: 'Diana', src: 'https://...' },
+    { name: 'Elena' },
+  ]}
+  max={3}
+/>
+
+// With overflow tap
+<AvatarGroup
+  users={waiters}
+  max={3}
+  size="sm"
+  onOverflowPress={() => showAllWaiters()}
+/>
+
+// In a ListItem
+<ListItem
+  title="Table 4 — 5 waiters"
+  leftRender={
+    <AvatarGroup
+      users={table.waiters}
+      max={3}
+      size="sm"
+    />
+  }
+/>
+```
+
+---
+
 ### Card
 
 **Import:** `import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@retray-dev/ui-kit'`
@@ -1763,73 +1824,7 @@ const [guests, setGuests] = useState(2)
 
 ---
 
-### VirtualList
 
-**Import:** `import { VirtualList } from '@retray-dev/ui-kit'`
-
-**When to use:** Large lists (100+ items) where you need efficient rendering. Thin wrapper over `FlatList` with sane defaults for stable keys and optional fixed-height fast path.
-
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| data | `T[]` | — | Array of items to render |
-| renderItem | `ListRenderItem<T>` | — | Render function for each item |
-| itemHeight | `number` | — | Fixed row height in px. Enables `getItemLayout` for performance with large datasets |
-| keyExtractor | `(item: T, index: number) => string` | Auto | Defaults to `item.id` or index. Override for custom keys |
-| ...FlatListProps | — | — | All standard FlatList props pass through |
-
-**Performance optimization:** When `itemHeight` is provided, `VirtualList` enables `getItemLayout` so FlatList skips async measurement. For 10k+ rows, combine with `React.memo`-wrapped `renderItem` so only on-screen rows mount and re-render.
-
-**Default key extraction:** Uses `item.id` (converted to string) or falls back to index. Override with `keyExtractor` for custom logic.
-
-**Example — simple list:**
-```tsx
-<VirtualList
-  data={items}
-  renderItem={({ item }) => (
-    <ListItem
-      title={item.title}
-      subtitle={item.subtitle}
-      onPress={() => handlePress(item.id)}
-    />
-  )}
-  itemHeight={56}
-/>
-```
-
-**Example — large dataset with memoized render:**
-```tsx
-const renderItem = useCallback(({ item }) => (
-  <ListItem
-    title={item.title}
-    subtitle={item.subtitle}
-    leftIcon="circle"
-    showSeparator
-    onPress={() => navigate('detail', { id: item.id })}
-  />
-), [])
-
-<VirtualList
-  data={thousands}
-  renderItem={renderItem}
-  itemHeight={64}
-/>
-```
-
-**Example — variable height rows (omit itemHeight):**
-```tsx
-<VirtualList
-  data={posts}
-  renderItem={({ item }) => (
-    <Card style={{ margin: SPACING.sm }}>
-      <CardContent>
-        <Text>{item.content}</Text>
-      </CardContent>
-    </Card>
-  )}
-/>
-```
-
----
 
 ### Separator
 
@@ -1902,6 +1897,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` | — | — |
@@ -1943,7 +1939,7 @@ const renderItem = useCallback(({ item }) => (
 // Matches <ListItem> — leading circle + title/subtitle lines
 <Skeleton.ListItem />                              // props: showAvatar, showSubtitle, style
 
-// Repeated list/grid placeholder — for VirtualList / FlatList while loading.
+// Repeated list/grid placeholder — for FlatList while loading.
 // columns=1 → stacked ListItemSkeleton; columns>1 → grid of MediaCardSkeleton.
 <Skeleton.List count={6} />                         // stacked list
 <Skeleton.List count={6} columns={2} />             // 2-col card grid
@@ -1951,8 +1947,8 @@ const renderItem = useCallback(({ item }) => (
 
 // Also exported as named components: MediaCardSkeleton, ListItemSkeleton, ListSkeleton
 
-// As a VirtualList loading state
-<VirtualList
+// As a FlatList loading state
+<FlatList
   data={loading ? [] : rows}
   renderItem={renderItem}
   ListEmptyComponent={loading ? <Skeleton.List count={8} /> : <EmptyState .../>}
@@ -2349,6 +2345,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'`
@@ -2510,6 +2594,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.
 }
 ```
 
@@ -3980,12 +4065,13 @@ export default function TabLayout() {
 | 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 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.
+**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:
 
@@ -4237,6 +4323,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` | — | — |
 
@@ -4331,10 +4418,12 @@ const [icon, setIcon] = useState<string | null>(null)
 
 **Import:** `import { useConfirmDialog } from '@retray-dev/ui-kit'`
 
-**When to use:** Manage `ConfirmDialog` state without boilerplate. Replaces the `[target, setTarget]` + `visible` + `loading` state pattern that each screen would otherwise duplicate.
+**When to use:** Manage `ConfirmDialog` state without boilerplate. Replaces the `visible` + `loading` state pattern that each screen would otherwise duplicate.
+
+**Note (v13):** The generic `T`, `target`, and `dialogProps` convenience object were removed. Returns `onConfirm`/`onCancel` directly. Uses refs for callback stability and `mountedRef` for safe async cleanup.
 
 ```ts
-function useConfirmDialog<T>(options: UseConfirmDialogOptions): UseConfirmDialogResult<T>
+function useConfirmDialog(options: UseConfirmDialogOptions): UseConfirmDialogResult
 
 interface UseConfirmDialogOptions {
   onConfirm: () => void | Promise<void>
@@ -4347,34 +4436,30 @@ interface UseConfirmDialogOptions {
 | Field | Type | Notes |
 |-------|------|-------|
 | visible | `boolean` | Pass to `ConfirmDialog.visible` |
-| target | `T \| null` | The value passed to `open()` — e.g. the item being deleted |
 | loading | `boolean` | Pass to `ConfirmDialog.loading` |
-| open | `(target?: T) => void` | Call to show the dialog |
-| dialogProps | `object` | Spread directly onto `<ConfirmDialog>` (contains `visible`, `loading`, `onConfirm`, `onCancel`) |
+| open | `() => void` | Call to show the dialog |
+| onConfirm | `() => void` | Pass directly to `ConfirmDialog.onConfirm` |
+| onCancel | `() => void` | Pass directly to `ConfirmDialog.onCancel` |
 
 **Example:**
 ```tsx
-const { open, target, dialogProps } = useConfirmDialog<Product>({
+const { visible, loading, open, onConfirm, onCancel } = useConfirmDialog({
   onConfirm: async () => {
-    await deleteProduct(target!.id)
+    await deleteProduct(productId)
     toast.success('Product deleted')
   },
 })
 
-// Somewhere in your list:
-<ListItem
-  title={product.name}
-  rightIcon="trash-2"
-  onPress={() => open(product)}
-/>
-
-// Once in your screen's JSX:
+// Somewhere in your screen:
 <ConfirmDialog
-  title={`Delete "${target?.name}"?`}
-  description="This action cannot be undone."
+  visible={visible}
+  title="Delete product?"
+  subtitle="This action cannot be undone."
   confirmLabel="Delete"
   confirmVariant="destructive"
-  {...dialogProps}
+  loading={loading}
+  onConfirm={onConfirm}
+  onCancel={onCancel}
 />
 ```
 
@@ -4388,12 +4473,12 @@ The library ships a built-in icon resolver — pass any icon name string to comp
 
 | Priority | Family | Best for |
 |---|---|---|
-| 1 (highest) | `Feather` | Clean line icons, UI essentials |
+| 1 | `Feather` | Clean line icons, UI essentials (first match wins) |
 | 2 | `AntDesign` | Semantic UI icons |
 | 3 | `Entypo` | Social, media, navigation icons |
 | 4 | `FontAwesome5` | Wide coverage |
 | 5 | `MaterialIcons` | Material-style icons |
-| 6 (lowest) | `Ionicons` | Fallback |
+| 6 | `Ionicons` | Fallback |
 
 Browse all available icons: **https://icons.expo.fyi**
 
@@ -4420,29 +4505,7 @@ import { Icon } from '@retray-dev/ui-kit'
 
 Returns `null` (no crash) if name not found in any family.
 
-### `renderIcon` helper
-
-```tsx
-import { renderIcon } from '@retray-dev/ui-kit'
-
-// Returns ReactNode or null
-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.
+> **v13:** `renderIcon`, `getValidIconNames`, and `configureIconFamilies` were removed. Use `Icon` component directly for all icon rendering.
 
 ### `iconName` props on components
 
@@ -4506,33 +4569,6 @@ getResponsiveFontSize(text, 48, [
 
 ---
 
-## Hover Support (Web)
-
-```tsx
-import { useHover } from '@retray-dev/ui-kit'
-
-function MyHoverableComponent() {
-  const { hovered, hoverHandlers } = useHover()
-
-  return (
-    <View
-      {...hoverHandlers}
-      style={[
-        styles.container,
-        hovered && { backgroundColor: colors.surfaceStrong }
-      ]}
-    />
-  )
-}
-```
-
-- **Web:** Returns `{ hovered: boolean, hoverHandlers: { onMouseEnter, onMouseLeave } }`
-- **Native:** Always returns `{ hovered: false, hoverHandlers: {} }` — no-op, no crashes
-
-Built-in web hover: `MediaCard` (shadow lift), interactive components use this internally.
-
----
-
 ## Design System Conventions
 
 ### Touch targets
@@ -4562,7 +4598,7 @@ All interactive elements maintain ≥44pt touch height per Apple HIG:
 - `useNativeDriver` — `Platform.OS !== 'web'` everywhere (native driver disabled on web)
 - `Select` — wheel modal on iOS, dialog on Android, `<select>` on web
 - `Toast` — full width on mobile, 400px centered on web
-- Hover states — web only via `useHover()`
+- Hover states — web only
 - `Skeleton` shimmer highlight — adapts opacity for light/dark mode
 
 ### Dynamic Type

package/CONSUMER.md

@@ -32,6 +32,7 @@ npx expo install \
   expo-haptics \
   expo-linear-gradient \
   expo-font \
+  expo-image \
   react-native-reanimated \
   react-native-gesture-handler \
   react-native-worklets \
@@ -48,7 +49,7 @@ npx expo install \
   pressto
 ```
 
-> `react-native-ease` and `pressto` are hard required. Omitting either crashes every component at module load — you will see a blank screen with no error message on screen.
+> `react-native-ease` and `pressto` are hard required. Omitting either crashes every component at module load — you will see a blank screen with no error message on screen. `expo-image` is required for image-based components (Avatar, MediaCard, ListItem, ImageUpload, ImageViewer).
 
 ---
 
@@ -56,7 +57,6 @@ npx expo install \
 
 ```bash
 npx expo install expo-image-picker   # Required only for ImageUpload component
-npx expo install react-native-pulsar # Richer haptic feedback (graceful fallback to expo-haptics when absent)
 
 # HolographicCard only — deep-import, NOT in main barrel:
 npx expo install @shopify/react-native-skia expo-sensors

package/DESIGN.md

@@ -324,7 +324,7 @@ Shape language is **soft everywhere**. Buttons use `{rounded.md}` (14px) — a f
 - Sohne type family. Display weights 600–700. Body weight 400. Modest weight is intentional.
 - 8pt spacing grid with 4pt micro-steps. Section bands at `{spacing.section}` (64px).
 - Maximum two elevation tiers — flat baseline (95% of surfaces) plus one card float tier.
-- Haptics on every interaction via `react-native-pulsar` with `expo-haptics` fallback.
+- Haptics on every interaction via `expo-haptics`.
 - Press animations via `pressto` — main-thread, gesture-handler worklets. Color transitions via `react-native-reanimated` v4.
 
 ## Colors
@@ -602,7 +602,7 @@ All pressables: `enabled={!disabled}`, `rippleColor="transparent"`, `touchSoundD
 
 ## Haptic Feedback
 
-All haptics via `src/utils/haptics.ts` — `react-native-pulsar` with `expo-haptics` fallback. Pulsar loads dynamically via `import()` inside a try/catch; absent in Expo Go, graceful fallback.
+All haptics via `src/utils/haptics.ts` — `expo-haptics`.
 
 | Function | Use |
 |---|---|

package/README.md

@@ -3,7 +3,7 @@
 A personal React Native / Expo UI component library with a built-in design system, dark mode support, haptic feedback, and smooth animations.
 
 - 54 components across 9 categories (plus the deep-import `HolographicCard`)
-- Light/dark theme with 12 public tokens (25 resolved) and full customization
+- Light/dark theme with 12 public tokens (26 resolved) and full customization
 - Apple HIG–compliant touch targets and haptic feedback
 - Animated interactions: spring press, sliding tabs, accordion easing, animated progress
 - Built with TypeScript — full type declarations included
@@ -23,14 +23,16 @@ pnpm add @retray-dev/ui-kit
 Install these in your app if not already present:
 
 ```bash
-pnpm add expo-font expo-haptics expo-linear-gradient react-native-safe-area-context @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-worklets @react-native-picker/picker @react-native-community/slider @expo/vector-icons react-native-size-matters react-native-svg react-native-screens sonner-native pressto react-native-ease expo-image-picker
+pnpm add expo-font expo-haptics expo-linear-gradient expo-image react-native-safe-area-context @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-worklets @react-native-picker/picker @react-native-community/slider @expo/vector-icons react-native-size-matters react-native-svg react-native-screens sonner-native pressto react-native-ease expo-image-picker
 ```
 
 For Expo projects, run `npx expo install` instead to get SDK-compatible versions.
 
 `pressto` is **required** — it powers the press animations on every interactive component. Omitting it crashes the import. `sonner-native` is **required** for `Toast`.
 
-**Optional:** for richer haptics in a custom dev build (not Expo Go), also `pnpm add react-native-pulsar`. The kit falls back to `expo-haptics` automatically when it is absent. For `ImageUpload`, add `expo-image-picker`. For the deep-import `HolographicCard`, add `@shopify/react-native-skia expo-sensors`.
+**Required:** `expo-image` is required for `Avatar`, `ImageUpload`, `ImageViewer`, `ListItem`, and `MediaCard` image rendering. It replaces React Native's built-in `Image` with caching, blurhash placeholders, and cross-fade transitions.
+
+**Optional:** for `ImageUpload`, add `expo-image-picker`. For the deep-import `HolographicCard`, add `@shopify/react-native-skia expo-sensors`.
 
 Add the Worklets Babel plugin to `babel.config.js` (required by `@gorhom/bottom-sheet`):
 
@@ -156,7 +158,7 @@ const { colors, colorScheme } = useTheme()
 
 **Public tokens (12 — override these):** `background`, `foreground`, `card`, `primary`, `primaryForeground`, `border`, `destructive`, `destructiveForeground`, `success`, `successForeground`, `warning`, `warningForeground`. Optional: `overlay`, `accent`, `accentForeground`.
 
-**Derived tokens (read-only via `useTheme()`):** `foregroundSubtle`, `foregroundMuted`, `surface`, `surfaceStrong`, `destructiveTint`, `destructiveBorder`, `successTint`, `successBorder`, `warningTint`, `warningBorder`, `ring`, `input`, `separator`, `overlay`, `accentResolved`, `accentForegroundResolved`
+**Derived tokens (read-only via `useTheme()`):** `foregroundSubtle`, `foregroundMuted`, `surface`, `surfaceStrong`, `skeleton`, `destructiveTint`, `destructiveBorder`, `successTint`, `successBorder`, `warningTint`, `warningBorder`, `ring`, `input`, `separator`, `overlay`, `accentResolved`, `accentForegroundResolved`
 
 ## Design Tokens
 
@@ -179,7 +181,8 @@ import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS, TYPOGRAPHY } from '@
 
 ### 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.
+- **`withAlpha(hex: 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.
+- **`hexToRgb(hex: string)`** — returns `{ r, g, b } | null`. Converts hex color to RGB components.
 
 ## Components
 
@@ -187,12 +190,12 @@ import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS, TYPOGRAPHY } from '@
 | ----------- | ----------------------------------------------------------------------------------------------- |
 | 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` |
+| Form        | `Form` (+ `Form.Field` / `Form.Section` / `Form.Footer`), `Button`, `ButtonGroup`, `IconButton`, `Input`, `CurrencyInput`, `Textarea`, `Checkbox`, `Switch`, `Toggle`, `RadioGroup`, `Select`, `Slider`, `SelectableGrid`, `SelectableCard` (+ `SelectableCardGroup`), `SheetSelect`, `ImageUpload`, `IconPicker`, `NumberStepper` |
 | Composition | `Tabs`, `Accordion`                                                                             |
 | Navigation  | `AppHeader`, `TabBar`, `PagerDots`                                                              |
 | Overlays    | `Sheet`, `ConfirmDialog`, `ImageViewer`                                                         |
 | Feedback    | `Toast` / `ToastProvider` / `useToast`                                                          |
-| Data        | `ListItem`, `ListGroup` (+ `.Header` / `.Footer`), `MenuItem`, `MenuGroup` (+ `.Header` / `.Footer`), `VirtualList`, `Chip` / `ChipGroup`, `LabelValue`, `MonthPicker`, `CategoryStrip`, `DetailRow` |
+| Data        | `ListItem`, `ListGroup` (+ `.Header` / `.Footer`), `MenuItem`, `MenuGroup` (+ `.Header` / `.Footer`), `Chip` / `ChipGroup`, `LabelValue`, `MonthPicker`, `CategoryStrip`, `DetailRow` |
 | Utilities   | `Pressable`, `Icon`, `RetrayProvider`, `ErrorBoundary`                                          |
 
 Deep-import only: `HolographicCard` — `import { HolographicCard } from '@retray-dev/ui-kit/HolographicCard'`.
@@ -226,9 +229,11 @@ toast({ title: 'Saved', variant: 'success' })
 />
 
 // Color utilities
-import { useTheme, withAlpha } from '@retray-dev/ui-kit'
+import { useTheme, withAlpha, hexToRgb } from '@retray-dev/ui-kit'
 const { colors } = useTheme()
 ;<View style={{ backgroundColor: withAlpha(colors.primary, 0.15) }} />
+// hexToRgb — converts hex to RGB components
+const rgb = hexToRgb('#6366f1') // { r: 99, g: 102, b: 241 }
 ```
 
 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.d.mts

@@ -11,6 +11,12 @@ interface AccordionItem {
     icon?: React.ReactNode;
     /** Override icon color. Defaults to foregroundMuted. */
     iconColor?: string;
+    /**
+     * Action buttons rendered after the trigger content but before the chevron.
+     * Automatically touch-isolated — taps on actions won't toggle the accordion.
+     * Use this instead of embedding interactive elements inside `trigger`.
+     */
+    triggerActions?: React.ReactNode;
 }
 interface AccordionProps {
     items: AccordionItem[];

package/dist/Accordion.d.ts

@@ -11,6 +11,12 @@ interface AccordionItem {
     icon?: React.ReactNode;
     /** Override icon color. Defaults to foregroundMuted. */
     iconColor?: string;
+    /**
+     * Action buttons rendered after the trigger content but before the chevron.
+     * Automatically touch-isolated — taps on actions won't toggle the accordion.
+     * Use this instead of embedding interactive elements inside `trigger`.
+     */
+    triggerActions?: React.ReactNode;
 }
 interface AccordionProps {
     items: AccordionItem[];