@retray-dev/ui-kit 7.0.1 → 9.1.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v7.0.1)
+# @retray-dev/ui-kit — Component Reference (v9.1.0)
 
 This file is the AI reference for this package. It is shipped inside the npm package so consuming projects can import it into their `CLAUDE.md` with:
 
@@ -11,7 +11,27 @@ This file is the AI reference for this package. It is shipped inside the npm pac
 
 ## Setup (Required)
 
-Wrap your app root with all required providers in this exact order:
+### Recommended: `RetrayProvider` (one wrapper)
+
+Since v8, a single `RetrayProvider` wires all five required providers in the correct order — use this and skip the manual nesting:
+
+```tsx
+import { RetrayProvider } from '@retray-dev/ui-kit'
+
+export default function App() {
+  const [fontsLoaded] = useFonts(SohneFonts)
+  if (!fontsLoaded) return null
+  return (
+    <RetrayProvider colorScheme="system">
+      {/* your app */}
+    </RetrayProvider>
+  )
+}
+```
+
+### Manual (equivalent) — if you need a custom tree
+
+`RetrayProvider` is exactly this; the individual providers stay exported. Order is mandatory:
 
 ```tsx
 import { SafeAreaProvider, initialWindowMetrics } from 'react-native-safe-area-context'
@@ -42,6 +62,66 @@ export default function App() {
 - `BottomSheetModalProvider` must be inside `GestureHandlerRootView`
 - `ToastProvider` wraps children and renders `Toaster` (from `sonner-native`) internally
 
+### Peer dependencies
+
+Install all required peers (Expo projects: swap `pnpm add` for `npx expo install` to get SDK-pinned versions):
+
+```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
+```
+
+Then add the Worklets Babel plugin to `babel.config.js` (required by `@gorhom/bottom-sheet` and the pressable animations):
+
+```js
+module.exports = function (api) {
+  api.cache(true)
+  return {
+    presets: ['babel-preset-expo'],
+    plugins: ['react-native-worklets/plugin'], // NOT react-native-reanimated/plugin
+  }
+}
+```
+
+| Peer | Required? | Used by | Notes |
+|------|-----------|---------|-------|
+| `pressto` | **Required** | Every interactive component | Press-scale animations (`src/utils/pressable.ts`). Static import via the barrel — omitting it crashes the module load, not just one component. |
+| `sonner-native` | **Required** | `Toast` | Also pulls `react-native-svg` + `react-native-screens`. |
+| `react-native-reanimated` (≥4.0) | **Required** | Animations, `Sheet`, pressables | Needs the `react-native-worklets/plugin` Babel plugin. |
+| `react-native-gesture-handler` | **Required** | `Sheet`, pressables | Wrap app in `GestureHandlerRootView`. |
+| `@gorhom/bottom-sheet` (≥5.2.0) | **Required** | `Sheet`, `ConfirmDialog` | 5.1.x crashes on Reanimated v4. |
+| `expo-haptics` | **Required** | Haptic feedback (all interactions) | Web-safe wrapper, no-op on web. |
+| `expo-font` | **Required** | All `Text` | Load `SohneFonts` at app root before rendering. |
+| `expo-linear-gradient` | **Required** | `Skeleton` shimmer | |
+| `@react-native-picker/picker` | **Required** | `Select` | |
+| `@react-native-community/slider` | **Required** | `Slider` | |
+| `@expo/vector-icons` | **Required** | Icons everywhere | |
+| `react-native-size-matters` | **Required** | Responsive scaling | |
+| `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
+
+Toast pulls `sonner-native`, which imports `react-native-screens` via its `src/*` path. On **React Native 0.83** that source trips a `@react-native/codegen` parse error (`CT.WithDefault` not parseable). It is a `react-native-screens` issue, not the kit — but since Toast surfaces it, add this resolver to your `metro.config.js` to force the compiled `lib/commonjs` build:
+
+```js
+// metro.config.js
+const { getDefaultConfig } = require('expo/metro-config')
+const config = getDefaultConfig(__dirname)
+
+const defaultResolveRequest = config.resolver.resolveRequest
+config.resolver.resolveRequest = (context, moduleName, platform) => {
+  // Force react-native-screens to its compiled output, bypassing the src codegen bug.
+  if (moduleName.startsWith('react-native-screens/src')) {
+    moduleName = moduleName.replace('react-native-screens/src', 'react-native-screens/lib/commonjs')
+  }
+  return (defaultResolveRequest ?? context.resolveRequest)(context, moduleName, platform)
+}
+
+module.exports = config
+```
+
 ## Typography — Sohne (Required)
 
 All components use **Sohne** as the font family. You **must** load it before rendering any UI kit component.
@@ -454,6 +534,41 @@ The example app now has a dedicated **Compound Components** section showcasing `
 
 ---
 
+## Migration Guide: v7 → v8
+
+### Breaking Changes
+
+**1. New required peer dependency: `sonner-native`**
+Toast (`ToastProvider` / `toast` / `useToast`) imports `sonner-native`, but it was never declared as a peer — installs silently lacked it and Metro failed with `Unable to resolve "sonner-native"`. It is now a declared peer. Install it:
+```bash
+pnpm add sonner-native
+```
+(You already need its companions `react-native-svg` and `react-native-screens`.)
+
+**2. `@gorhom/bottom-sheet` peer range tightened to `>=5.2.0`**
+5.1.x crashes with Reanimated v4 (`useWorkletCallback is not a function`), which broke `Sheet`, `ConfirmDialog`, and `Select` on open. The range no longer admits broken versions. Pin `5.2.8` if you also use Worklets `0.5.x`.
+
+**3. `./fonts` stays at `src/fonts.ts` (unchanged)**
+The `./fonts` export deliberately points at `src/fonts.ts`, not `dist`. The `.otf` files ship as raw assets in `src/assets/fonts/` and are resolved by Metro at your build time via `require()`. Compiling this entry to `dist` and repointing the `require()` paths breaks Metro asset resolution under pnpm symlinked workspaces (`requiring unknown module ../src/assets/fonts/...`), so it is intentionally left as source. No API change — import as before:
+```ts
+import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+```
+
+### New — packaging & DX
+
+- **`RetrayProvider`** — one wrapper replacing the five-provider boilerplate (see Setup below).
+- **Dev font guard** — if you render a UI kit component without loading `SohneFonts`, `Text` now logs a one-time `console.warn` in dev (silent in production) instead of failing invisibly.
+
+### New components
+
+`RetrayProvider`, `AppHeader`, `TabBar`, `PagerDots`, `SelectableGrid`, `PricingCard`, `ErrorBoundary`, `ImageViewer`, plus `Skeleton.MediaCard` / `Skeleton.ListItem` sub-skeletons and the optional deep-import-only `HolographicCard` (Skia foil card). `MonthPicker` gained `minValue`/`maxValue` and `Date` bridge helpers.
+
+### Optional peers (only if you use the matching component)
+
+- `@shopify/react-native-skia` + `expo-sensors` → `HolographicCard` (deep-import only, not in the main barrel).
+
+---
+
 ## Components
 
 ---
@@ -548,6 +663,8 @@ The example app now has a dedicated **Compound Components** section showcasing `
 | iconColor | `string` | — | Override icon color. Defaults to variant label color |
 | iconPosition | `'left' \| 'right'` | `'left'` | Side the icon appears on |
 | style | `ViewStyle` | — | Override container style |
+| accessibilityLabel | `string` | — | Screen reader label. Defaults to `label` |
+| accessibilityHint | `string` | — | Screen reader hint |
 
 **Variants:**
 
@@ -689,6 +806,8 @@ The example app now has a dedicated **Compound Components** section showcasing `
 | badge | `boolean \| number` | — | Notification badge overlay |
 | disabled | `boolean` | — | Reduces opacity to 0.5 |
 | style | `ViewStyle` | — | — |
+| accessibilityLabel | `string` | — | Screen reader label |
+| accessibilityHint | `string` | — | Screen reader hint |
 
 **Variants:** Same token logic as Button.
 
@@ -704,7 +823,7 @@ The example app now has a dedicated **Compound Components** section showcasing `
 
 | Size | Dimensions | Icon size |
 |------|-----------|-----------|
-| `sm` | 32 × 32px | 16px |
+| `sm` | 44 × 44px | 18px |
 | `md` | 44 × 44px | 20px |
 | `lg` | 52 × 52px | 24px |
 
@@ -765,6 +884,7 @@ The example app now has a dedicated **Compound Components** section showcasing `
 | label | `string` | — | Label above the input field |
 | error | `string` | — | Error text below — turns border `destructive` (2px) |
 | hint | `string` | — | Helper text below (hidden when `error` is set) |
+| disabled | `boolean` | — | Reduces opacity to 0.5, disables interaction |
 | prefix | `string \| ReactNode` | — | Content before the input text (e.g. `"$"`, icon node) |
 | suffix | `string \| ReactNode` | — | Content after the input text (e.g. `"kg"`, icon node) |
 | prefixStyle | `TextStyle` | — | Style for prefix string (no effect on ReactNode) |
@@ -1469,15 +1589,29 @@ const renderItem = useCallback(({ item }) => (
 </View>
 ```
 
-**Composition — skeleton for a ListItem:**
+**Sub-skeletons (v8):** ready-made placeholders that mirror a component's footprint, so grids/lists don't reflow when real data arrives.
+
 ```tsx
-<View style={{ flexDirection: 'row', gap: SPACING.md, padding: SPACING.base }}>
-  <Skeleton preset="circle" diameter={40} />
-  <View style={{ flex: 1, gap: SPACING.xs }}>
-    <Skeleton height={16} width="60%" />
-    <Skeleton preset="text" />
-  </View>
-</View>
+// Matches <MediaCard> — image block + title/subtitle lines
+<Skeleton.MediaCard aspectRatio="4:3" />          // props: aspectRatio ('1:1'|'4:3'|'16:9'|'4:5'|'3:2'), showSubtitle, style
+
+// Matches <ListItem> — leading circle + title/subtitle lines
+<Skeleton.ListItem />                              // props: showAvatar, showSubtitle, style
+
+// Repeated list/grid placeholder — for VirtualList / 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
+// props: count, columns, gap, aspectRatio (grid), showAvatar (list), style
+
+// Also exported as named components: MediaCardSkeleton, ListItemSkeleton, ListSkeleton
+
+// As a VirtualList loading state
+<VirtualList
+  data={loading ? [] : rows}
+  renderItem={renderItem}
+  ListEmptyComponent={loading ? <Skeleton.List count={8} /> : <EmptyState .../>}
+/>
 ```
 
 ---
@@ -1581,6 +1715,8 @@ const renderItem = useCallback(({ item }) => (
 | iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` |
 | iconColor | `string` | — | Override icon color. Defaults to `foregroundMuted` |
 | action | `ReactNode` | — | CTA below text — typically a `Button`. Hidden in `compact` size |
+| actionLabel | `string` | — | Shorthand for a primary `Button` CTA — renders a default `Button` with this label. Requires `onAction`. Hidden in `compact` size |
+| onAction | `() => void` | — | Handler for the shorthand `actionLabel` button. Required when `actionLabel` is set |
 | size | `'default' \| 'compact'` | `'default'` | `compact` is smaller, hides description and action |
 | style | `ViewStyle` | — | — |
 
@@ -2082,7 +2218,8 @@ Add `react-native-worklets/plugin` (not `react-native-reanimated/plugin`) to `ba
 | open | `boolean` | required | `true` presents the sheet, `false` dismisses it |
 | onClose | `() => void` | required | Called on swipe-dismiss or backdrop press |
 | title | `string` | — | Sheet heading |
-| subtitle | `string` | — | Supporting text below title (replaces deprecated `description`) |
+| 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 |
@@ -2095,10 +2232,13 @@ 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
 - Backdrop press dismisses
 - **Scrollable content:** use `scrollable` prop or `maxHeight`. Both use `BottomSheetScrollView` — do NOT use plain `ScrollView` inside Sheet
@@ -2896,6 +3036,7 @@ const [categories, setCategories] = useState<number[]>([1, 3])
 | multiSelect | `boolean` | `false` | Allow multiple simultaneous selections |
 | style | `ViewStyle` | — | ScrollView content container style |
 | itemStyle | `ViewStyle` | — | Style applied to each chip's wrapper |
+| accessibilityLabel | `string` | — | Screen reader label for the scroll container |
 
 **CategoryItem type:**
 ```ts
@@ -3078,6 +3219,8 @@ Total ·············· $50.000
 |------|------|---------|-------|
 | value | `MonthPickerValue` | required | `{ month: 1–12, year: number }` |
 | onChange | `(value: MonthPickerValue) => void` | required | Called on navigation |
+| minValue | `MonthPickerValue` | — | Earliest selectable month (inclusive). Prev arrow disables + dims at this bound |
+| maxValue | `MonthPickerValue` | — | Latest selectable month (inclusive). Next arrow disables + dims at this bound — e.g. cap at the current month |
 | locale | `string` | `'en'` | BCP 47 locale. Built-in: `'en'`, `'es'`, `'pt'`, `'fr'`. Other locales: use `formatLabel` |
 | formatLabel | `(value: MonthPickerValue) => string` | — | Custom label formatter. Takes precedence over `locale` |
 | style | `ViewStyle` | — | — |
@@ -3087,7 +3230,15 @@ Total ·············· $50.000
 { month: number; year: number }  // month is 1-indexed (January = 1)
 ```
 
-**Navigation:** Year wraps correctly at boundaries (December → January increments year, January → December decrements year). Fully controlled — no internal state.
+**Date bridge helpers** (exported): for domains that store `Date` (e.g. finance apps in a fixed TZ), convert at the boundary instead of changing your model.
+```ts
+import { dateToMonthPickerValue, monthPickerValueToDate } from '@retray-dev/ui-kit'
+
+dateToMonthPickerValue(new Date())          // → { month, year } (local time)
+monthPickerValueToDate({ month: 6, year: 2026 })  // → Date at first day of the month
+```
+
+**Navigation:** Year wraps correctly at boundaries (December → January increments year, January → December decrements year). When `minValue`/`maxValue` are set, the boundary arrow is disabled (opacity 0.3) and presses are ignored. Fully controlled — no internal state.
 
 **Styling:** Centered row with `←` / `→` buttons (44×44px each). Label: 17pt / Medium / 160px min-width, centered.
 
@@ -3186,6 +3337,407 @@ const [period, setPeriod] = useState({
 
 ---
 
+### RetrayProvider
+
+**Import:** `import { RetrayProvider } from '@retray-dev/ui-kit'`
+
+**When to use:** At your app root, instead of hand-nesting the five required providers. Removes an entire class of provider-order bugs. The individual providers stay exported for custom trees.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `ReactNode` | required | Your app |
+| theme | `Theme` | — | Per-scheme token overrides, forwarded to `ThemeProvider` |
+| colorScheme | `'system' \| 'light' \| 'dark'` | `'system'` | Forwarded to `ThemeProvider` |
+
+**Wraps (in order):** `SafeAreaProvider` (with `initialWindowMetrics`) → `GestureHandlerRootView` → `ThemeProvider` → `BottomSheetModalProvider` → `ToastProvider`.
+
+**Example:**
+```tsx
+import { RetrayProvider } from '@retray-dev/ui-kit'
+
+export default function App() {
+  const [fontsLoaded] = useFonts(SohneFonts)
+  if (!fontsLoaded) return null
+  return (
+    <RetrayProvider colorScheme="system" theme={{ light: { primary: '#ff385c' } }}>
+      <RootNavigator />
+    </RetrayProvider>
+  )
+}
+```
+
+---
+
+### AppHeader
+
+**Import:** `import { AppHeader } from '@retray-dev/ui-kit'`
+
+**When to use:** Top app bar / screen chrome — back button, title/subtitle, and a right action slot. Responsive: title left-aligns on phones and centers when width ≥ `BREAKPOINTS.wide`.
+
+**Expo Router compatibility:** ✅ Fully compatible. Use with `useRouter()` for navigation:
+
+```tsx
+import { useRouter } from 'expo-router'
+import { AppHeader } from '@retray-dev/ui-kit'
+
+export default function Screen() {
+  const router = useRouter()
+  return (
+    <AppHeader 
+      title="Settings" 
+      onBack={() => router.back()} 
+      right={<IconButton iconName="more-horizontal" variant="text" />} 
+    />
+  )
+}
+```
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| title | `string` | — | Primary title (truncates to 1 line) |
+| subtitle | `string` | — | Secondary line under the title |
+| onBack | `() => void` | — | Shows a back button on the left when provided |
+| backIconName | `string` | `'chevron-left'` | Icon for the back button |
+| left | `ReactNode` | — | Custom left content — overrides the back button |
+| right | `ReactNode` | — | Custom right content (actions) |
+| titleAlign | `'auto' \| 'left' \| 'center'` | `'auto'` | `auto` = left on narrow, centered on wide |
+| bordered | `boolean` | `true` | Hairline border underneath |
+| withSafeArea | `boolean` | `true` | Apply top safe-area inset as padding |
+| backgroundColor | `string` | `colors.background` | — |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+<AppHeader
+  title="Settings"
+  onBack={navigation.goBack}
+  right={<IconButton iconName="more-horizontal" variant="text" onPress={openMenu} />}
+/>
+```
+
+---
+
+### TabBar
+
+**Import:** `import { TabBar } from '@retray-dev/ui-kit'`
+
+**When to use:** Bottom tab navigation — icon + label tabs with active tint and badges. Pair with your navigator, or drive with local state for a single-screen app.
+
+**Expo Router compatibility:** ✅ Fully compatible. Use in `_layout.tsx` to build custom tab navigation:
+
+```tsx
+// app/(tabs)/_layout.tsx
+import { Tabs, useRouter, useSegments } from 'expo-router'
+import { TabBar } from '@retray-dev/ui-kit'
+
+export default function TabLayout() {
+  const router = useRouter()
+  const segments = useSegments()
+  const activeKey = segments[1] || 'home'
+
+  return (
+    <Tabs
+      tabBar={() => (
+        <TabBar
+          items={[
+            { key: 'home', label: 'Home', iconName: 'home' },
+            { key: 'search', label: 'Search', iconName: 'search' },
+            { key: 'profile', label: 'Profile', iconName: 'user', badge: 3 },
+          ]}
+          activeKey={activeKey}
+          onTabPress={(key) => router.push(`/(tabs)/${key}`)}
+        />
+      )}
+    >
+      {/* ... screens */}
+    </Tabs>
+  )
+}
+```
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| items | `TabBarItem[]` | required | `{ key, label?, iconName?, icon?, badge? }` |
+| activeKey | `string` | required | Key of the active tab |
+| onTabPress | `(key: string) => void` | required | — |
+| activeColor | `string` | `colors.primary` | — |
+| inactiveColor | `string` | `colors.foregroundMuted` | — |
+| withSafeArea | `boolean` | `true` | Apply bottom safe-area inset |
+| style | `ViewStyle` | — | — |
+
+**TabBarItem.badge:** `true` shows a dot; a number shows a count (capped at `99+`).
+
+**Haptics:** `selectionAsync` when switching to a new tab.
+
+**Example:**
+```tsx
+<TabBar
+  activeKey={tab}
+  onTabPress={setTab}
+  items={[
+    { key: 'home', label: 'Home', iconName: 'home' },
+    { key: 'wallet', label: 'Wallet', iconName: 'credit-card' },
+    { key: 'profile', label: 'Profile', iconName: 'user', badge: 3 },
+  ]}
+/>
+```
+
+---
+
+### PagerDots
+
+**Import:** `import { PagerDots } from '@retray-dev/ui-kit'`
+
+**When to use:** Page indicator for carousels / document pagers. The active dot stretches into a pill and color-crossfades — all on the UI thread. Now supports optional previous/next control buttons.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| count | `number` | required | Total pages |
+| activeIndex | `number` | required | 0-based active page |
+| onDotPress | `(index: number) => void` | — | Omit to make dots non-interactive |
+| showControls | `boolean \| { onPrevious?, onNext? }` | `false` | Show prev/next buttons. If `true`, uses `onDotPress(activeIndex ± 1)`. If object, uses custom handlers |
+| dotSize | `number` | `8` | Inactive dot diameter (dp) |
+| spacing | `number` | `8` | Gap between dots (dp) |
+| activeColor | `string` | `colors.primary` | — |
+| inactiveColor | `string` | `colors.border` | — |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+<PagerDots count={pages.length} activeIndex={page} onDotPress={setPage} showControls />
+```
+
+---
+
+### SelectableGrid
+
+**Import:** `import { SelectableGrid } from '@retray-dev/ui-kit'`
+
+**When to use:** Grid of selectable cells (icon + label) — store / category / emoji pickers where a list would be the wrong shape. Single or multi select. Generic over the value type (`string | number`). Now supports horizontal scrolling mode for single-row layouts.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| items | `SelectableGridItem<T>[]` | required | `{ value, label?, iconName?, icon?, disabled? }` |
+| value | `T \| T[] \| null` | required | Selected value(s) — array when `multiple` |
+| onChange | `(value: T) => void` | required | Fires with the toggled item's value |
+| multiple | `boolean` | `false` | Allow multiple selection (`value` should be an array) |
+| numColumns | `number` | `4` | Cells per row (exact-fit width is measured, not percentage). Ignored when `orientation='horizontal'` |
+| gap | `number` | `12` | Gap between cells (dp) |
+| orientation | `'grid' \| 'horizontal'` | `'grid'` | `'grid'` wraps into rows, `'horizontal'` creates a single scrollable row |
+| style | `ViewStyle` | — | — |
+
+**Selected cell:** primary border + tinted background; icon/label switch to `primary`. **Press scale:** chip (0.94). **Haptics:** `selectionAsync` on press.
+
+**Horizontal mode:** Fixed 96dp cell width, horizontal ScrollView, no vertical wrapping.
+
+**Example:**
+```tsx
+{/* Grid layout */}
+<SelectableGrid
+  items={categories}
+  value={category}
+  onChange={setCategory}
+  numColumns={4}
+/>
+
+{/* Horizontal scrolling */}
+<SelectableGrid
+  items={categories}
+  value={category}
+  onChange={setCategory}
+  orientation="horizontal"
+/>
+```
+
+**Example:**
+```tsx
+<SelectableGrid
+  items={[
+    { value: 'food', label: 'Food', iconName: 'coffee' },
+    { value: 'transport', label: 'Transport', iconName: 'truck' },
+    { value: 'home', label: 'Home', iconName: 'home' },
+  ]}
+  value={category}
+  onChange={setCategory}
+  numColumns={4}
+/>
+```
+
+---
+
+### PricingCard
+
+**Import:** `import { PricingCard } from '@retray-dev/ui-kit'`
+
+**When to use:** Paywalls and freemium tiers — price header, feature list with check marks, optional promo badge, and CTA. Set `highlighted` on the recommended plan.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| name | `string` | required | Plan name |
+| price | `string` | required | Formatted price, e.g. `"$9"` or `"Free"` |
+| period | `string` | — | Billing suffix, e.g. `"/mo"` |
+| description | `string` | — | Short text under the price |
+| features | `(string \| PricingFeature)[]` | `[]` | Strings = included; `{ label, included: false }` for excluded (dashed, struck) |
+| ctaLabel | `string` | — | CTA button label (renders a `Button`) |
+| onCtaPress | `() => void` | — | — |
+| badge | `string` | — | Promo badge, e.g. `"Most popular"` |
+| highlighted | `boolean` | `false` | Primary border + elevation + primary CTA |
+| footnote | `string` | — | Small print under the CTA |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+<PricingCard
+  name="Pro"
+  price="$9"
+  period="/mo"
+  badge="Most popular"
+  highlighted
+  features={['Unlimited docs', 'Priority support', { label: 'SSO', included: false }]}
+  ctaLabel="Start trial"
+  onCtaPress={subscribe}
+  footnote="Cancel anytime"
+/>
+```
+
+---
+
+### ErrorBoundary
+
+**Import:** `import { ErrorBoundary } from '@retray-dev/ui-kit'`
+
+**When to use:** Wrap screens or risky subtrees so a render error shows a themed fallback instead of unmounting the whole app.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `ReactNode` | required | Protected subtree |
+| fallback | `ReactNode \| (props: { error, reset }) => ReactNode` | themed card | Custom fallback |
+| title | `string` | `'Something went wrong'` | Default fallback title |
+| message | `string` | `error.message` | Default fallback body |
+| onError | `(error, info) => void` | — | Wire your crash reporter here |
+
+**Default fallback:** centered themed card with a destructive icon, title, message, and a "Try again" button that calls `reset()`.
+
+**Example:**
+```tsx
+<ErrorBoundary onError={reportCrash}>
+  <DocumentViewer />
+</ErrorBoundary>
+
+// Custom fallback
+<ErrorBoundary fallback={({ error, reset }) => <MyFallback error={error} onRetry={reset} />}>
+  <RiskyScreen />
+</ErrorBoundary>
+```
+
+---
+
+### ImageViewer
+
+**Import:** `import { ImageViewer } from '@retray-dev/ui-kit'`
+
+**When to use:** Full-screen zoomable image gallery — multi-page documents, photo viewers. Horizontal paging + pinch / double-tap zoom + pan, with page dots and a close button. Requires `react-native-gesture-handler` (already a peer).
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| images | `ImageSourcePropType[]` | required | `{ uri }` or `require()` sources |
+| visible | `boolean` | required | Controls the modal |
+| onClose | `() => void` | required | — |
+| initialIndex | `number` | `0` | Page to open on |
+
+**Behavior:** pinch to zoom (max 3×), double-tap to toggle 2.5× zoom, pan while zoomed. Paging locks automatically while a page is zoomed in. `PagerDots` shown when there is more than one image.
+
+**Example:**
+```tsx
+<ImageViewer
+  images={doc.pages.map((uri) => ({ uri }))}
+  visible={viewerOpen}
+  initialIndex={page}
+  onClose={() => setViewerOpen(false)}
+/>
+```
+
+---
+
+### HolographicCard
+
+**Import (deep import only):** `import { HolographicCard, FOIL_PRESETS, FoilPreset } from '@retray-dev/ui-kit/HolographicCard'`
+
+> Not re-exported from the main barrel — it depends on the **optional** peers `@shopify/react-native-skia` and `expo-sensors`, which are deliberately kept out of the main module graph. Deep-import it so consumers who don't use it never pull Skia.
+
+**When to use:** Holographic / foil trading-card surface (Pokémon-TCG style). Renders art on a Skia canvas with an animated rainbow sheen and tilts in 3D toward device motion; the sheen tracks the tilt so the foil "catches the light".
+
+**Install:** `pnpm add @shopify/react-native-skia expo-sensors`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| source | `require()` / `{ uri }` | — | Card art. Omitted = gradient-only foil surface |
+| width | `number` | `300` | Card width (dp) |
+| height | `number` | `width * 1.4` | Trading-card ratio by default |
+| borderRadius | `number` | `RADIUS.md` | — |
+| enableTilt | `boolean` | `true` | React to gyroscope. No-op on web; static sheen if `expo-sensors` is absent |
+| intensity | `number` | `1` | Foil sheen strength, 0–1 |
+| onPress | `() => void` | — | Adds card press-scale + `impactLight` |
+| style | `ViewStyle` | — | — |
+| foilPreset | `FoilPreset` | `'rainbow'` | Foil color preset. Ignored if `foilColors` is provided |
+| foilColors | `string[]` | — | Custom foil gradient colors (array of RGBA strings). Overrides `foilPreset` |
+| maxTiltDegrees | `number` | `10` | Maximum tilt angle in degrees (0–45) |
+| tiltSensitivity | `number` | `1` | Sensitivity of tilt to device motion (0.1–2). Higher = more responsive |
+| sheenSpread | `number` | `0.6` | How far the sheen moves relative to tilt (0–1) |
+| tiltAnimationDuration | `number` | `80` | Animation duration for tilt smoothing in ms |
+| perspective | `number` | `800` | Perspective depth for 3D effect (200–2000) |
+| blendMode | `string` | `'plus'` | Blend mode: `'plus'` \| `'screen'` \| `'overlay'` \| `'softLight'` \| `'hardLight'` |
+
+**Available foil presets (`FoilPreset`):**
+
+| Preset | Description |
+|--------|-------------|
+| `rainbow` | Classic holographic rainbow (default) |
+| `gold` | Premium gold foil |
+| `silver` | Chrome silver foil |
+| `cosmic` | Deep space cosmic |
+| `emerald` | Emerald green luxury |
+| `rose` | Rose gold / pink |
+| `ocean` | Deep ocean blue |
+| `fire` | Hot fire gradient |
+| `aurora` | Aurora borealis |
+| `neon` | Neon cyberpunk |
+
+**Example:**
+```tsx
+import { HolographicCard, FOIL_PRESETS } from '@retray-dev/ui-kit/HolographicCard'
+
+// Basic usage
+<HolographicCard source={require('./assets/card.png')} width={320} onPress={openCard} />
+
+// Gold foil preset with higher tilt
+<HolographicCard
+  source={{ uri: 'https://example.com/card.png' }}
+  width={280}
+  foilPreset="gold"
+  maxTiltDegrees={25}
+  tiltSensitivity={1.5}
+  intensity={0.9}
+/>
+
+// Custom foil colors
+<HolographicCard
+  width={280}
+  foilColors={[
+    'rgba(255, 0, 0, 0.5)',
+    'rgba(255, 255, 0, 0.4)',
+    'rgba(0, 255, 0, 0.5)',
+  ]}
+  blendMode="screen"
+  perspective={1200}
+/>
+
+// Foil-only surface (no image)
+<HolographicCard foilPreset="cosmic" width={200} maxTiltDegrees={30} />
+```
+
+---
+
 ## Icon System
 
 The library ships a built-in icon resolver — pass any icon name string to components without manual imports.
@@ -3366,11 +3918,12 @@ Used internally — not exported. `s()` horizontal scale, `vs()` vertical scale,
 
 ## Full Composition Examples
 
-The package includes **EXAMPLES.md** with complete, working code for 3 real-world app screens:
+The package includes **EXAMPLES.md** with complete, working code for 4 real-world app screens:
 
 1. **Finance Dashboard** — MonthPicker, CurrencyDisplay, Progress, CategoryStrip, ListItem, DetailRow
 2. **Edit Profile** — Avatar, Badge, Input, Select, Switch, Card, AlertBanner
 3. **Onboarding Flow** — Badge, Progress, Input, RadioGroup, EmptyState (multi-step wizard)
+4. **Settings Screen** — MenuGroup, ListGroup, Form, MenuItem, ListItem, compound component patterns
 
 **For AI agents:** Import EXAMPLES.md from the package for full source code and patterns: