@retray-dev/ui-kit 12.2.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
 
@@ -1561,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'`
@@ -1765,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
 
@@ -1946,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
@@ -1954,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 .../>}
@@ -4425,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>
@@ -4441,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}
 />
 ```
 
@@ -4482,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**
 
@@ -4514,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
 
@@ -4600,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
@@ -4656,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

@@ -2,7 +2,7 @@
 
 A personal React Native / Expo UI component library with a built-in design system, dark mode support, haptic feedback, and smooth animations.
 
-- 55 components across 9 categories (plus the deep-import `HolographicCard`)
+- 54 components across 9 categories (plus the deep-import `HolographicCard`)
 - Light/dark theme with 12 public tokens (26 resolved) and full customization
 - Apple HIG–compliant touch targets and haptic feedback
 - Animated interactions: spring press, sliding tabs, accordion easing, animated progress
@@ -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`):
 
@@ -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
 
@@ -192,7 +195,7 @@ import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS, TYPOGRAPHY } from '@
 | 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: