@retray-dev/ui-kit 12.2.0 → 13.2.0

package/CONSUMER.md

@@ -1,15 +1,30 @@
-# @retray-dev/ui-kit — Consumer Setup Guide (v10.1.0)
+# @retray-dev/ui-kit — Consumer Setup Guide (v13.2.0)
 
-> **For AI assistants (Claude Code):** Add all three lines below to your project's `CLAUDE.md` so Claude has full context about this UI kit:
-> ```markdown
-> ## UI Components
-> @./node_modules/@retray-dev/ui-kit/COMPONENTS.md
-> @./node_modules/@retray-dev/ui-kit/CONSUMER.md
-> @./node_modules/@retray-dev/ui-kit/EXAMPLES.md
-> ```
+## AI Assistant Context (Claude Code)
+
+**Step 1 — Copy docs to your repo root:**
+
+```bash
+cp node_modules/@retray-dev/ui-kit/SKILL.md SKILL.md
+cp node_modules/@retray-dev/ui-kit/CONSUMER.md CONSUMER.md
+cp node_modules/@retray-dev/ui-kit/EXAMPLES.md EXAMPLES.md
+```
+
+> `@./node_modules/...` paths work but break when `node_modules` is regenerated or absent (CI cache miss, new clone). Copying files to repo root guarantees Claude always has context regardless of install state. Re-copy on upgrades.
+
+**Step 2 — Add to `CLAUDE.md`:**
+
+```markdown
+## UI Kit
+@./SKILL.md
+@./CONSUMER.md
+@./EXAMPLES.md
+```
 
 ---
 
+
+
 ## Prerequisites
 
 | Requirement | Minimum | Notes |
@@ -32,6 +47,7 @@ npx expo install \
   expo-haptics \
   expo-linear-gradient \
   expo-font \
+  expo-image \
   react-native-reanimated \
   react-native-gesture-handler \
   react-native-worklets \
@@ -48,15 +64,14 @@ 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).
 
 ---
 
 ## Install: Optional Peer Dependencies
 
 ```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)
+npx expo install react-native-image-picker   # Required only for ImageUpload component
 
 # 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

@@ -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
 ```
 
 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 `react-native-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`):
 
@@ -175,24 +177,25 @@ import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS, TYPOGRAPHY } from '@
 | `RADIUS` | `none` (0), `xs` (4), `sm` (8), `md` (14), `lg` (20), `xl` (32), `full` (9999) |
 | `SHADOWS` | `sm`, `md`, `lg`, `xl` — cross-platform shadow presets |
 | `BREAKPOINTS` | `wide` (700) |
-| `TYPOGRAPHY` | 16 variants: `display-hero`, `display-xl`, `display-lg`, `display-md`, `display-sm`, `title-md`, `title-sm`, `body-md`, `body-sm`, `caption`, `caption-sm`, `badge-text`, `micro-label`, `uppercase-tag`, `button-lg`, `button-sm` |
+| `TYPOGRAPHY` | 17 variants: `display-hero`, `display-xl`, `display-lg`, `display-md`, `display-sm`, `title-md`, `title-sm`, `body-md`, `body-sm`, `caption`, `caption-sm`, `badge-text`, `badge-text-md`, `micro-label`, `uppercase-tag`, `button-lg`, `button-sm` |
 
 ### 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. Import from package root.
 
 ## Components
 
 | Category    | Components                                                                                      |
 | ----------- | ----------------------------------------------------------------------------------------------- |
-| Display     | `Text`, `Badge`, `Avatar`, `Separator`, `Spinner`, `Skeleton`, `Progress`, `CurrencyDisplay`, `Stats` |
+| Display     | `Text`, `Badge`, `Avatar`, `AvatarGroup`, `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`, `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,17 +229,18 @@ 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:
+Full props reference and more examples are available in [SKILL.md](./SKILL.md), which is also shipped inside the npm package for use with AI tools:
 
 ```markdown
-## UI Components
-
-@./node_modules/@retray-dev/ui-kit/COMPONENTS.md
+## UI Kit
+@./node_modules/@retray-dev/ui-kit/SKILL.md
 ```
 
 ## License