@retray-dev/ui-kit 13.0.0 → 13.4.0

package/CHANGELOG.md

@@ -0,0 +1,680 @@
+# Changelog
+
+All notable changes to `@retray-dev/ui-kit`.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Semver bump type in brackets.
+
+---
+
+## [13.4.0] — 2026-07-01 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+
+**New:**
+- `useSheetModal` hook — shared BottomSheetModal state machine extracted from Sheet and ConfirmDialog. Exported from barrel: `import { useSheetModal } from '@retray-dev/ui-kit'`
+
+**Changes:**
+- Accordion: removed `useDerivedValue`, inlined `withTiming` directly in `useAnimatedStyle` — fewer worklet nodes, same behavior
+- Sheet/ConfirmDialog: migrated to `useSheetModal` hook — removes duplicated state machine logic from both components
+- Haptics: switched from dynamic `import()` (async, per-call) to static `import * as Haptics` at module init — synchronous, no async overhead
+- Icon resolution: removed lazy singleton glyph cache — introspects `glyphMap` per render call (simpler, no memory leak risk)
+- `curatedIcons.ts`: removed lazy singleton cache — pure functions only
+- Color derivation: removed unused `withAlphaOnWhite`, `withAlphaOnDark`, `lighten`, `darken` internal helpers — replaced with `createColorPair` + `mixWithBackground`
+- Shadow presets (lg/xl): reduced opacity and elevation for softer elevation feel — `lg` now `0.12/12/8`, `xl` now `0.18/24/16`
+- `ErrorBoundary`: removed `onCatch` prop (minor breaking — use `onError` instead)
+- `Select`: DRY refactor — extracted `renderPickerItems` to remove duplicated Picker.Item rendering across platforms
+- `ListGroup`/`MenuGroup`: extracted shared `ItemGroup` internal component — `ListGroup` and `MenuGroup` are now thin wrappers with `childPropKey`
+
+### Peer Dep Changes
+None.
+
+---
+
+## [13.2.0] — 2026-06-30 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+
+**New:**
+- `AppHeader`: now accepts `iconName` prop for `@expo/vector-icons` icon
+- Side padding in `AppHeader` fixed — now `s(16)` consistent with design system
+- `AvatarGroup` demo added to example app
+
+**Changes:**
+- `expo-image-picker` → `react-native-image-picker` (peer dep changed)
+- `ImageUpload` now uses `react-native-image-picker` directly (dynamic import at tap time)
+- `ConfirmDialog` / `Sheet` state management improved — cleanup on `onDismiss`
+- ESLint strict type checks enabled
+- Added unit tests across multiple components
+- Dependencies updated to latest compatible versions
+
+### Peer Dep Changes
+- **REMOVE** `expo-image-picker` (no longer used)
+- **ADD** `react-native-image-picker` (>=7.0.0, optional — only for ImageUpload)
+
+```bash
+pnpm remove expo-image-picker
+pnpm add react-native-image-picker
+```
+
+---
+
+## [13.0.0] — 2026-06-25 (major)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### Breaking Changes
+- **VirtualList removed** — was deprecated, not exported from barrel
+- Accessibility labels in Spanish (es-UI mode)
+- All UI text now in Spanish (placeholders, accessibility labels, buttons, errors)
+
+### What Changed
+
+**New:**
+- Compound `Sheet` + `AvatarGroup` export structure
+- `opencode.json` config for project
+- All UI documentation updated
+
+**Changes:**
+- Accessibility: `PagerDots` improved hitSlop, labels in Spanish
+- Demo screens modularized
+- ESLint configuration improved
+- Removed unused guard utilities and color transition helpers
+- Haptic feedback / pressable components simplified
+- `expo-image` integration for Avatar, MediaCard, ListItem, ImageUpload, ImageViewer
+
+---
+
+## [12.2.0] — 2026-06-22 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+
+**New:**
+- `SelectableCard` + `SelectableCardGroup` components for selection UI
+- Additional derived theme tokens
+
+**Changes:**
+- Theme system enhanced with more tokens
+- Documentation improved across components
+
+---
+
+## [12.1.0] — 2026-06-20 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+
+**New:**
+- Migration guides for v10 → v11 → v12
+- Improved `ConfirmDialog` and `IconPicker` state management
+
+**Changes:**
+- Component structure cleaned up
+- Component count corrected in README
+
+---
+
+## [12.0.0] — 2026-06-18 (major)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### Breaking Changes
+- **`responsive` / `dialogMaxWidth` props removed** from `Sheet` and `ConfirmDialog` — previously bypassed `@gorhom/bottom-sheet` with native `Modal` + `ScrollView` on wide screens. This created two code paths. Now gorhom handles responsive natively.
+- **`BottomSheetModal` pattern enforced** — always `present()` in handler, never `useEffect`. `useEffect` + `snapToIndex(0)` is banned.
+- **`enableDynamicSizing` without `snapPoints`** — never use both together.
+- **`SheetTextInput` required** inside Sheet — regular `TextInput` breaks keyboard handling.
+
+### What Changed
+- Sheet/ConfirmDialog migrated to strict `@gorhom/bottom-sheet` patterns
+- `BottomSheetModalProvider` re-exported from library
+
+---
+
+## [11.0.0] — 2026-06-15 (major)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### Breaking Changes
+- **`Stats` component added** — was previously internal
+- **`withAlpha` and `hexToRgb`** now exported as public API utilities
+
+### What Changed
+
+**New:**
+- `Stats` component for metric/stat displays
+- `withAlpha(hex, alpha)` — converts hex to rgba string
+- `hexToRgb(hex)` — returns `{ r, g, b }` | null
+
+---
+
+## [10.2.0] — 2026-06-14 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+
+**New:**
+- `IconPicker` — visual icon grid picker with categories
+- `NumberStepper` — increment/decrement numeric input
+
+**Deps:**
+- `expo-image-picker` added as optional peer (for IconPicker media)
+
+```bash
+pnpm add expo-image-picker
+```
+
+---
+
+## [10.1.0] — 2026-06-13 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+- Documentation updates with new commands and component details
+- `.gitignore` cleanup
+
+---
+
+## [10.0.0] — 2026-06-12 (major)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### Breaking Changes
+- **Font system overhauled** — fonts no longer embedded in package. Now copied via **postinstall script** (`scripts/copy-fonts.js`) to consumer's `assets/fonts/sohne/`.
+- **Consumer must define font `require()` calls** — Metro cannot resolve `require()` inside `node_modules`.
+- **Font verification script added** — `npx @retray-dev/ui-kit verify-fonts` to validate installation.
+
+### Migration from v9
+
+**Before (v9):** Fonts loaded automatically at module init via internal `require()`.
+
+**After (v10):**
+1. Postinstall copies 28 `.otf` files to `assets/fonts/sohne/`
+2. Define `SohneFonts` in `App.tsx` with static `require()` (see CONSUMER.md for boilerplate)
+3. Pass to `expo-font` `useFonts()` hook before rendering UI kit components
+4. Add `assets/fonts/sohne/` to `.gitignore` (optional)
+
+```bash
+# After install, fonts are at:
+assets/fonts/sohne/
+```
+
+---
+
+## [9.3.1] — 2026-06-11 (patch)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+- Font verification script added
+- Font path resolution fixed (avoid traversal issues)
+
+---
+
+## [9.3.0] — 2026-06-10 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+
+**New:**
+- Jest test infrastructure (config, setup, mocks for native modules)
+- Unit tests for existing components
+
+**Changes:**
+- `ListItem` enhancements
+- `Input` component improvements
+- Testing commands added: `pnpm test`, `pnpm test:watch`, `pnpm test:coverage`
+
+---
+
+## [9.2.0] — 2026-06-09 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+
+**New:**
+- `SheetSelect` — sheet-based select component
+- `ImageUpload` — image picker/upload component
+- Consumer setup guide (CONSUMER.md)
+
+**Changes:**
+- `Pressable` component props updated
+- Haptics module imports improved
+- Toast usage updated for consistency
+
+---
+
+## [9.0.0] — 2026-06-09 (major)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### Breaking Changes
+- **`react-native-ease` required** — replaces custom Reanimated animation wrappers across Checkbox, Chip, CategoryStrip, Switch, RadioGroup, Toggle. Static `EaseView` import at module level — omitting it crashes.
+- **`pressto` required** — replaces custom pressable components with `createAnimatedPressable`. All interactive components now use `pressto` pressables. Omitting it crashes module load.
+- **Haptic feedback refactored** — `src/utils/haptics.ts` now uses dynamic `import()` inside function bodies (never at module init) behind `Platform.OS !== 'web'` guard.
+- **`react-native-pulsar` fallback removed** — haptics use `expo-haptics` exclusively.
+
+### Migration from v8
+
+**New required peers:**
+```bash
+pnpm add react-native-ease pressto
+```
+
+**Babel plugin (critical):**
+```js
+// babel.config.js — use worklets plugin, NOT reanimated plugin
+plugins: ['react-native-worklets/plugin']
+```
+
+### What Changed
+
+**New:**
+- `HolographicCard` — Skia-powered holographic effect (deep import: `@retray-dev/ui-kit/HolographicCard`)
+- `ErrorBoundary` — error boundary component
+- `PricingCard` — pricing plan card
+- `SelectableGrid` — grid selection component
+- `SurfacesScreen`, `ThemeScreen` for example app
+
+**Changes:**
+- All interactive components migrated to `pressto` pressables + `react-native-ease` animations
+- `Pressable` component refactored (no more `bounciness` prop)
+- `Button`, `Checkbox`, `RadioGroup`, `Select`, `Tabs`, `Toast`, `Toggle` animations rebuilt with `react-native-ease`
+- Performance: components converted to `memo`-ized versions
+- `@gorhom/bottom-sheet` pinned to `5.2.8` (fix for Reanimated v4 crash)
+- Padding/separator colors standardized
+- Safe area crash fix on Android (added `initialWindowMetrics`)
+- Lint and TS errors fixed
+
+---
+
+## [7.0.1] — 2026-06-02 (patch)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+- `VirtualList` component added (later removed in v13)
+- Safe area crash fix for Android
+- `@gorhom/bottom-sheet` downgraded to `5.2.8` (compatibility)
+
+---
+
+## [6.1.0] — 2026-05-21 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+
+**New:**
+- `subtitle` prop on `MenuItem`
+- `DetailRow` value type enhanced
+
+**Changes:**
+- Documentation updated
+
+---
+
+## [6.0.0] — 2026-05-21 (major)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### Breaking Changes
+- **Theme system tokens restructured** — new token set with derived colors
+- `ThemeColors` interface expanded
+
+### What Changed
+
+**New:**
+- Migration guide for v5 → v6
+- New theme tokens: `overlay`, `accent`, `accentForeground`
+- Derived tokens: `foregroundSubtle`, `foregroundMuted`, `surface`, `surfaceStrong`, `skeleton`, `*Tint`, `*Border`, `ring`, `input`, `separator`, `overlay`, `accentResolved`, `accentForegroundResolved`
+
+**Changes:**
+- UI feedback improved across components
+- Bottom sheet margins and animations enhanced
+- Example app expanded
+
+---
+
+## [5.4.0] — 2026-05-15 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+- `Button` icon color customization (`iconColor` prop)
+- Theme customizer in component showcase
+
+---
+
+## [5.3.0] — 2026-05-12 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+
+**New:**
+- `DetailRow` component
+
+---
+
+## [5.2.0] — 2026-05-10 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+- `EXAMPLES.md` composition patterns guide
+- Documentation and example app enhancements
+
+---
+
+## [5.1.0] — 2026-05-09 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+
+**New:**
+- `ChipGroup` component
+- `CategoryStrip` component
+
+**Changes:**
+- Documentation with new component categories
+
+---
+
+## [5.0.0] — 2026-05-08 (major)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### Breaking Changes
+- **Airbnb-inspired redesign** — all components visually overhauled
+- **`RADIUS` tokens changed** — `md=14px` (buttons), `sm=8px` (inputs), `lg=12px` (cards), `xl=16px` (sheet top corners)
+- **Touch targets enforced** — all interactive ≥44pt minimum
+- **Haptic pattern standardized** — `selectionAsync` on toggle, `impactLight` on button, etc.
+- **Press scale tokens standardized** — Button 0.95, Card 0.98, ListItem 0.97, Chip 0.94
+- **`SHADOWS` presets added** — sm/md/lg/xl cross-platform shadow system
+- **Typography variants restructured** — 17 variants from `display-xl` through `micro-label`
+
+### What Changed
+- Complete visual redesign with softer shapes, generous spacing, single accent color
+- Color system: 90% background + foreground surfaces, one primary moment
+- `ICON_SIZES` added (HIG roles)
+- `SPACING` 8pt grid with 4pt micro-steps
+- Spring/timing/easing animation tokens standardized
+- All interactive components support `iconName` prop
+
+---
+
+## [4.0.0] — 2026-04-27 (major)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### Breaking Changes
+- **`ConfirmDialog` and `Sheet` use `enableDynamicSizing`** — height auto-fits content, `snapPoints` no longer accepted
+- **`AlertBanner` props enforced** — some props now required
+- **`CurrencyInput` props enforced**
+
+### What Changed
+- `AlertBanner` styling updated
+- `Input` now supports `inputWrapperStyle` prop
+- Documentation improved
+
+---
+
+## [3.0.0] — 2026-04-25 (major)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### Breaking Changes
+- **Typography section restructured** — font families, sizes, weights reorganized
+- **Color tokens expanded** — 12 public tokens with derived system
+
+### What Changed
+- Claude Design styles integrated
+- Design system foundations established
+
+---
+
+## [2.8.0] — 2026-04-20 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+
+**New:**
+- `IconButton` component (circular pressable icon, `RADIUS.full`)
+
+---
+
+## [2.7.0] — 2026-04-18 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+
+**New:**
+- Design tokens: `SPACING`, `ICON_SIZES`, `RADIUS`, `SHADOWS`, `BREAKPOINTS`
+- TypeScript types for all tokens: `Spacing`, `IconSize`, `Radius`, etc.
+- Tokens are static `as const` objects — no provider needed
+
+---
+
+## [2.6.0] — 2026-04-15 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+
+**New:**
+- Icon resolution system (`src/utils/icons.ts`) — scans 6 `@expo/vector-icons` families (Feather > AntDesign > Entypo > FontAwesome5 > MaterialIcons > Ionicons)
+- `Icon` component — resolves icon names via glyphMap introspection, returns `null` if not found (no crash)
+- All components with icon slots now use `Icon` internally
+
+**Changes:**
+- Custom scaling utilities (`src/utils/scaling.ts`) — wraps `react-native-size-matters`, web-safe identity fallback
+- Haptic feedback utilities (`src/utils/haptics.ts`) — web-safe wrapper around `expo-haptics`
+
+---
+
+## [2.5.1] — 2026-04-10 (patch)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+- Documentation updated
+- New peer dependencies added
+
+---
+
+## [2.5.0] — 2026-04-10 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+- Typography and component styles updated across library
+- `Select` and `Slider` refactored with `@expo/libraries`
+- AI Theme customizer added
+- Theme system refactored to support core theme colors with derived palette
+- `Switch` and `Toggle` components enhanced
+- Custom scaling utilities added
+
+---
+
+## [1.8.0] — 2026-04-08 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+- `CurrencyDisplay` formatting options enhanced
+- `CurrencyInputLarge` component added
+- Modern banking-style UI
+- Working conventions and task guidelines added
+
+---
+
+## [1.5.0] — 2026-04-01 (minor)
+
+### Upgrade
+```bash
+pnpm add @retray-dev/ui-kit@latest
+```
+
+### What Changed
+- Animation system updated — Accordion and Toast now use `react-native-reanimated`
+- Animated press effects across components
+- `expo-linear-gradient` added as peer dependency
+- `touchSoundDisabled` added to interactive components
+
+---
+
+## [1.0.0] — 2026-03-31 (initial)
+
+### What Changed
+- Initial release
+- 30+ components across 6 categories: Display, Surfaces, Form, Composition, Navigation, Overlays, Feedback, Data, Utilities
+- Theme system with light/dark mode
+- `@gorhom/bottom-sheet` for modals
+- `expo-haptics` for haptic feedback
+- Sohne font family
+- TypeScript types for all components
+
+### Initial Peer Dependencies
+```bash
+npx expo install \
+  react-native-reanimated \
+  react-native-gesture-handler \
+  react-native-safe-area-context \
+  expo-haptics \
+  expo-linear-gradient \
+  expo-image \
+  @gorhom/bottom-sheet \
+  @expo/vector-icons \
+  react-native-size-matters
+```
+
+---
+
+## Appendix: Upgrade Paths
+
+### v9 → v10 (font system)
+1. Install: `npx expo install expo-font`
+2. Postinstall copies fonts to `assets/fonts/sohne/`
+3. Define `SohneFonts` with static `require()` in `App.tsx`
+4. Use `useFonts(SohneFonts)` before rendering
+
+### v8 → v9 (ease + pressto)
+1. `pnpm add react-native-ease pressto`
+2. Update `babel.config.js`: `react-native-worklets/plugin` (not `react-native-reanimated/plugin`)
+3. `npx expo start --clear`
+
+### v5 → v6 (theme tokens)
+1. Add new tokens to your theme: `overlay`, `accent`, `accentForeground`
+2. Derived tokens computed automatically by `deriveColors()`
+
+### v4 → v5 (Airbnb redesign)
+1. Update `RADIUS` values in your custom themes
+2. Ensure all touch targets ≥44pt
+3. Verify typography variants match new 17-variant system
+
+### v3 → v4 (dynamic sizing)
+1. Remove `snapPoints` from `Sheet` and `ConfirmDialog`
+2. Replace `<TextInput />` with `<SheetTextInput />` inside Sheet children