@croacroa/react-native-template 2.1.0 → 3.2.0

package/docs/plans/2026-02-22-phase6-template-completion-design.md

@@ -0,0 +1,196 @@
+# Phase 6: Template Completion Design
+
+**Date:** 2026-02-22
+**Version:** 2.1.0 -> 3.0.0
+**Scope:** 7 new feature domains
+
+## Overview
+
+Complete the React Native template with 7 missing feature domains, using a mix of "clé en main" (turnkey) solutions and adapter pattern bases depending on the domain.
+
+## Domains
+
+### 1. Permission Management (Turnkey)
+
+**Goal:** Centralized permission handling with great UX.
+
+**Files:**
+- `services/permissions/permission-manager.ts` — Centralized service
+- `services/permissions/types.ts` — Permission types
+- `hooks/usePermission.ts` — Generic hook returning `{ status, request, openSettings }`
+- `components/ui/PermissionGate.tsx` — Wrapper component for permission-gated content
+
+**Features:**
+- Support: Camera, Location, Contacts, Media Library, Microphone, Notifications
+- "Don't ask again" detection with Settings redirect
+- First refusal tracking to adapt messaging
+
+**Dependencies:** `expo-camera`, `expo-location`, `expo-contacts`, `expo-media-library`
+
+---
+
+### 2. Animations / UX Polish (Turnkey)
+
+**Goal:** Production-quality animations and transitions out of the box.
+
+**Files:**
+- `utils/animations/transitions.ts` — Screen transition configs for Expo Router
+- `utils/animations/presets.ts` — Reusable animation presets
+- `hooks/useAnimatedEntry.ts` — Fade/slide-in on mount
+- `hooks/useParallax.ts` — Parallax effect for scroll
+- `components/ui/AnimatedScreen.tsx` — Screen wrapper with entry/exit animations
+- `components/ui/AnimatedList.tsx` — Stagger animation for list items
+
+**Features:**
+- Screen transition presets (slide, fade, modal) via Expo Router
+- Configurable entry animations (fade, slide-up, scale)
+- Cascade/stagger list item animations
+- Parallax scroll effect
+
+**Dependencies:** None new (uses existing `react-native-reanimated`)
+
+---
+
+### 3. Social Login (Turnkey)
+
+**Goal:** Google and Apple Sign-In ready to use.
+
+**Files:**
+- `services/auth/adapters/social/google.ts` — Google Sign-In adapter
+- `services/auth/adapters/social/apple.ts` — Apple Sign-In adapter
+- `services/auth/social-auth.ts` — Orchestrator
+- `components/auth/SocialLoginButtons.tsx` — Styled buttons (Apple/Google guidelines)
+- Update `app/(public)/login.tsx` with social buttons
+- Update `app.config.ts` with OAuth schemes
+
+**Features:**
+- Google Sign-In via `expo-auth-session`
+- Apple Sign-In via `expo-apple-authentication`
+- Integration with existing auth flow (Zustand store + token management)
+- Platform-aware (Apple Sign-In only on iOS)
+
+**Dependencies:** `expo-auth-session`, `expo-web-browser`, `expo-apple-authentication`, `expo-crypto`
+
+---
+
+### 4. Analytics (Adapter Pattern)
+
+**Goal:** Pluggable analytics with zero vendor lock-in.
+
+**Files:**
+- `services/analytics/analytics-adapter.ts` — Abstract interface
+- `services/analytics/adapters/console.ts` — Dev adapter (console.log)
+- `services/analytics/types.ts` — Event types
+- `hooks/useTrackScreen.ts` — Auto-track screen views
+- `hooks/useTrackEvent.ts` — Track custom events
+- `components/providers/AnalyticsProvider.tsx` — Provider initialization
+
+**Interface:**
+```typescript
+interface AnalyticsAdapter {
+  initialize(): Promise<void>;
+  track(event: string, properties?: Record<string, unknown>): void;
+  screen(name: string, properties?: Record<string, unknown>): void;
+  identify(userId: string, traits?: Record<string, unknown>): void;
+  reset(): void;
+}
+```
+
+**Dependencies:** None required (console adapter by default)
+
+---
+
+### 5. Payment Infrastructure (Adapter Pattern)
+
+**Goal:** Payment/subscription foundation with mock for dev.
+
+**Files:**
+- `services/payments/payment-adapter.ts` — Abstract interface
+- `services/payments/adapters/mock.ts` — Mock adapter for dev/testing
+- `services/payments/types.ts` — Product, Purchase, Subscription types
+- `hooks/useProducts.ts` — List products/plans
+- `hooks/usePurchase.ts` — Purchase flow
+- `hooks/useSubscription.ts` — Subscription status
+- `components/ui/Paywall.tsx` — Generic paywall component
+- `components/ui/PurchaseButton.tsx` — Purchase button with loading states
+
+**Interface:**
+```typescript
+interface PaymentAdapter {
+  initialize(): Promise<void>;
+  getProducts(ids: string[]): Promise<Product[]>;
+  purchase(productId: string): Promise<Purchase>;
+  restorePurchases(): Promise<Purchase[]>;
+  getSubscriptionStatus(): Promise<SubscriptionStatus>;
+}
+```
+
+**Dependencies:** None required (mock adapter by default)
+
+---
+
+### 6. File Upload / Media (Lightweight + Hooks)
+
+**Goal:** Image/video selection, compression, and upload with progress.
+
+**Files:**
+- `services/media/media-picker.ts` — Image/video selection wrapper
+- `services/media/media-upload.ts` — Upload with progress tracking
+- `services/media/compression.ts` — Image compression
+- `hooks/useImagePicker.ts` — Pick + compress + preview in one hook
+- `hooks/useUpload.ts` — Upload with progress, retry, cancel
+- `components/ui/ImagePickerButton.tsx` — Selection button
+- `components/ui/UploadProgress.tsx` — Progress bar component
+
+**Features:**
+- Image compression before upload (configurable quality)
+- Upload progress tracking
+- Retry and cancel support
+- Integration with permission system (camera/media library)
+
+**Dependencies:** `expo-image-manipulator`
+
+---
+
+### 7. WebSockets / Real-time (Lightweight + Hooks)
+
+**Goal:** WebSocket foundation with auto-reconnect and offline awareness.
+
+**Files:**
+- `services/realtime/websocket-manager.ts` — Connection manager
+- `services/realtime/types.ts` — Message types
+- `hooks/useWebSocket.ts` — Connection lifecycle hook
+- `hooks/useChannel.ts` — Channel subscription hook
+- `hooks/usePresence.ts` — User presence tracking
+
+**Features:**
+- Auto-reconnect with exponential backoff
+- Heartbeat/ping-pong
+- Offline queue (pause when offline, resume when online)
+- Auth token injection
+- Channel-based subscriptions
+- Presence tracking (online/offline users)
+
+**Dependencies:** None (uses native WebSocket API)
+
+---
+
+## New Dependencies Summary
+
+| Package | Purpose | Required |
+|---------|---------|----------|
+| `expo-camera` | Camera permissions | Yes |
+| `expo-location` | Location permissions | Yes |
+| `expo-contacts` | Contacts permissions | Yes |
+| `expo-media-library` | Media library permissions | Yes |
+| `expo-auth-session` | OAuth flows | Yes |
+| `expo-web-browser` | OAuth redirects | Yes |
+| `expo-apple-authentication` | Apple Sign-In | Yes |
+| `expo-crypto` | PKCE for OAuth | Yes |
+| `expo-image-manipulator` | Image compression | Yes |
+
+## Architecture Decisions
+
+- **Adapter pattern** for analytics and payments: consistent with existing auth adapter pattern (ADR-004)
+- **Turnkey** for permissions, animations, social login: universal needs, consistent implementation
+- **Lightweight hooks** for uploads and websockets: project-specific requirements vary too much for full integration

package/docs/plans/2026-02-23-npm-publish-design.md

@@ -0,0 +1,31 @@
+# npm Publish via GitHub Actions
+
+**Date:** 2026-02-23
+**Scope:** Version bump + CHANGELOG + CI workflow
+
+## Overview
+
+Publish `@croacroa/react-native-template` to npm automatically when a GitHub Release is created. Bump version from 2.1.0 to 3.2.0.
+
+## Changes
+
+### 1. `package.json` — version `3.2.0`
+
+### 2. `CHANGELOG.md` — Phase 7 + Phase 8 entries
+
+Add entries for:
+- Phase 7 (3.1.0): Screen i18n, Phase 6 hook tests, integration guides
+- Phase 8 (3.2.0): Rate limiting UI, force update, in-app review, crash recovery, feature flags, a11y tests, ETag caching
+
+### 3. `.github/workflows/npm-publish.yml`
+
+- Trigger: `on: release: types: [published]`
+- Validates tag matches package.json version
+- Runs lint + tests as quality gate
+- Publishes with `npm publish --access public`
+- Requires `NPM_TOKEN` secret in GitHub repo settings
+
+## Prerequisites
+
+- npm org `@croacroa` must exist on npmjs.com
+- `NPM_TOKEN` secret must be added to GitHub repo settings (Settings > Secrets > Actions)

package/docs/plans/2026-02-23-phase7-polish-documentation-design.md

@@ -0,0 +1,79 @@
+# Phase 7: Polish & Documentation Design
+
+**Date:** 2026-02-23
+**Version:** 3.0.0 → 3.1.0
+**Scope:** 3 improvement domains
+
+## Overview
+
+Strengthen the template with full i18n coverage across all screens, comprehensive tests for Phase 6 hooks, and concrete integration guides for the 3 most popular providers (Supabase, RevenueCat, PostHog).
+
+## Domain 1: Screen Internationalization
+
+**Goal:** Replace all hardcoded strings in the 6 app screens with i18n `t()` calls.
+
+**Screens:**
+- `app/(public)/login.tsx` — 9 hardcoded strings
+- `app/(public)/register.tsx` — 10 hardcoded strings
+- `app/(public)/forgot-password.tsx` — 10 hardcoded strings (zero i18n currently)
+- `app/(auth)/home.tsx` — 8 hardcoded strings
+- `app/(auth)/profile.tsx` — 6 hardcoded strings
+- `app/(auth)/settings.tsx` — 8 hardcoded strings
+
+**New i18n sections:**
+- `forgotPassword.*` (8 keys) — entirely new section
+- `home.*` (6 keys) — entirely new section
+
+**Extended sections:**
+- `auth.*` (+3 keys: createPasswordPlaceholder, confirmPasswordPlaceholder, passwordHintFull)
+- `profile.*` (+2 keys: privacySecurity, helpSupport)
+- `settings.*` (+2 keys: darkMode, appVersion)
+
+**Languages:** All 5 (en, fr, es, de, ar) updated to stay in sync.
+
+---
+
+## Domain 2: Phase 6 Hook Tests
+
+**Goal:** Add ~54 tests across 6 test files covering all 13 Phase 6 hooks.
+
+**Test files:**
+
+| File | Hooks | Tests |
+|------|-------|-------|
+| `__tests__/hooks/usePermission.test.ts` | usePermission | ~8 |
+| `__tests__/hooks/usePayments.test.ts` | useProducts, usePurchase, useSubscription | ~12 |
+| `__tests__/hooks/useMedia.test.ts` | useImagePicker, useUpload | ~10 |
+| `__tests__/hooks/useWebSocket.test.ts` | useWebSocket, useChannel, usePresence | ~12 |
+| `__tests__/hooks/useAnimations.test.ts` | useAnimatedEntry, useParallax | ~6 |
+| `__tests__/hooks/useAnalytics.test.ts` | useTrackScreen, useTrackEvent | ~6 |
+
+**Patterns:** Follow existing `useAuth.test.tsx` conventions — `renderHook`, `act`, `waitFor`, `jest.mock` for services, `QueryClientProvider` wrapper where needed.
+
+---
+
+## Domain 3: Adapter Integration Guides
+
+**Goal:** 3 copy-paste-ready guides for the most popular providers.
+
+**Files:**
+- `docs/guides/auth-supabase.md` — Supabase auth adapter (~100 lines)
+- `docs/guides/payments-revenuecat.md` — RevenueCat payment adapter (~100 lines)
+- `docs/guides/analytics-posthog.md` — PostHog analytics adapter (~100 lines)
+
+**Structure per guide:**
+1. Prerequisites & installation
+2. Environment configuration
+3. Full adapter implementation (complete, working code)
+4. Integration (which line to change)
+5. Verification steps
+
+**Providers chosen:** Supabase (auth), RevenueCat (payments), PostHog (analytics) — most popular in the React Native ecosystem.
+
+---
+
+## Architecture Decisions
+
+- **i18n:** Extend existing key structure, no breaking changes to existing keys
+- **Tests:** One file per domain (not one per hook) to keep test structure manageable
+- **Guides:** Standalone markdown files in `docs/guides/`, not ADRs (these are how-to, not decision records)

package/docs/plans/2026-02-23-phase8-additional-features-design.md

@@ -0,0 +1,136 @@
+# Phase 8: Additional Features Design
+
+**Date:** 2026-02-23
+**Version:** 3.1.0 → 3.2.0
+**Scope:** 8 features, ~17 files
+
+## Overview
+
+Complete the template with 8 remaining features identified during the post-Phase 6 audit: rate limiting UI, app force update, in-app review, crash recovery, feature flags with A/B testing, accessibility testing, and HTTP ETag caching.
+
+---
+
+## 1. Rate Limiting UI
+
+**Goal:** Give users feedback when API returns 429 Too Many Requests.
+
+**Changes:**
+- Modify `services/api.ts` — intercept 429 responses, extract `Retry-After` header, show toast, emit rate limit event
+- Create `hooks/useRateLimit.ts` — exposes `{ isRateLimited, retryAfter, resetTime }` for UI (disable buttons, show countdown)
+
+**i18n:** `errors.rateLimited` key in all 5 locales.
+
+---
+
+## 2. App Force Update
+
+**Goal:** Block the app when a mandatory native update is required.
+
+**Files:**
+- `services/force-update.ts` — checks a configurable endpoint, compares `currentVersion` (expo-constants) vs `minimumVersion` from server. Mock returns `isUpdateRequired: false` by default.
+- `hooks/useForceUpdate.ts` — checks on launch, returns `{ isUpdateRequired, storeUrl, currentVersion, minimumVersion }`
+- `components/ui/ForceUpdateScreen.tsx` — non-dismissible full-screen modal with "Update Now" button that opens the store URL
+
+**Config:** `FORCE_UPDATE_CHECK_URL` in constants/config.ts.
+
+**i18n:** `forceUpdate.title`, `forceUpdate.message`, `forceUpdate.button`.
+
+---
+
+## 3. In-App Review
+
+**Goal:** Request App Store / Play Store review after positive milestones.
+
+**Dependencies:** `expo-store-review`
+
+**Files:**
+- `hooks/useInAppReview.ts` — `{ requestReview, isAvailable, hasRequested }`
+- Throttle logic: tracks last prompt date in AsyncStorage, respects minimum days between prompts
+- Session counter in `appStore` (Zustand), incremented at root layout mount
+
+**Config:** `IN_APP_REVIEW.MIN_SESSIONS: 5`, `IN_APP_REVIEW.DAYS_BETWEEN_PROMPTS: 30`
+
+---
+
+## 4. Crash Recovery / Restart
+
+**Goal:** Add proper hard reset capability to the existing ErrorBoundary.
+
+**Changes to `components/ui/ErrorBoundary.tsx`:**
+- Two recovery levels: soft reset (existing re-render) and hard reset (clear nav + stores + `Updates.reloadAsync()`)
+- Consecutive crash counter: after 3 failed soft resets → auto-propose hard reset
+- Sentry context: send crash count for crash loop diagnostics
+
+**i18n:** `errors.crashTitle`, `errors.crashMessage`, `errors.tryAgain`, `errors.restartApp`
+
+---
+
+## 5. Feature Flags + A/B Testing (Adapter Pattern)
+
+**Goal:** Dynamic feature flags with experiment variant support.
+
+**Interface:**
+```typescript
+interface FeatureFlagAdapter {
+  initialize(): Promise<void>;
+  isEnabled(flag: string): boolean;
+  getValue<T>(flag: string, defaultValue: T): T;
+  getExperimentVariant(experimentId: string): string | null;
+  identify(userId: string, attributes?: Record<string, unknown>): void;
+  refresh(): Promise<void>;
+}
+```
+
+**Files:**
+- `services/feature-flags/types.ts` — types and interface
+- `services/feature-flags/feature-flag-adapter.ts` — FeatureFlags facade with `setAdapter()`
+- `services/feature-flags/adapters/mock.ts` — MockFeatureFlagAdapter (in-memory flags, configurable for dev/testing)
+- `hooks/useFeatureFlag.ts` — `{ isEnabled, isLoading }`
+- `hooks/useExperiment.ts` — `{ variant, isLoading }`
+- `components/ui/FeatureGate.tsx` — declarative show/hide based on flag (same pattern as PermissionGate)
+- `docs/guides/feature-flags-launchdarkly.md` — integration guide for LaunchDarkly
+
+**Config:** `FEATURE_FLAGS.REFRESH_INTERVAL_MS: 300000` (5 min)
+
+---
+
+## 6. Accessibility Testing
+
+**Goal:** Automated a11y tests for core UI components.
+
+**Files:**
+- `__tests__/helpers/a11y.ts` — reusable assertion helpers: `expectAccessibleButton()`, `expectAccessibleInput()`, `expectAccessibleImage()`. Checks: accessibilityRole, accessibilityLabel non-empty, accessibilityState correct.
+- `__tests__/accessibility/components.test.tsx` — tests Button, Input, Switch, Modal, Card for a11y compliance
+
+**Dependencies:** None new (uses existing @testing-library/react-native)
+
+---
+
+## 7. Network Caching / ETags
+
+**Goal:** Reduce bandwidth with HTTP conditional requests.
+
+**Changes to `services/api.ts`:**
+- In-memory ETag cache (Map<url, { etag, data }>)
+- On response: store ETag header + response body
+- On request: add `If-None-Match` header with cached ETag
+- On 304 response: return cached data without parsing body
+
+**Config:** `API_CONFIG.ENABLE_ETAG_CACHE: true` in constants/config.ts.
+
+---
+
+## 8. Supporting Changes
+
+**i18n keys (all 5 locales):**
+- `errors.rateLimited`
+- `forceUpdate.title`, `forceUpdate.message`, `forceUpdate.button`
+- `errors.crashTitle`, `errors.crashMessage`, `errors.tryAgain`, `errors.restartApp`
+
+**Config additions (constants/config.ts):**
+- `FORCE_UPDATE_CHECK_URL`
+- `IN_APP_REVIEW.MIN_SESSIONS`, `IN_APP_REVIEW.DAYS_BETWEEN_PROMPTS`
+- `FEATURE_FLAGS.REFRESH_INTERVAL_MS`
+- `API_CONFIG.ENABLE_ETAG_CACHE`
+
+**Barrel exports:** Update `hooks/index.ts`, `services/index.ts`, `components/ui/index.ts`

package/eas.json

@@ -1,6 +1,7 @@
 {
   "cli": {
-    "version": ">= 10.0.0"
+    "version": ">= 10.0.0",
+    "appVersionSource": "local"
   },
   "build": {
     "development": {

package/hooks/index.ts

@@ -1,40 +1,70 @@
-export { useAuth, AuthProvider, getAuthToken } from "./useAuth";
-export { useTheme, ThemeProvider } from "./useTheme";
-export { useNotifications } from "./useNotifications";
-export {
-  useCurrentUser,
-  useUser,
-  useUpdateUser,
-  useSuspenseCurrentUser,
-  useSuspenseUser,
-  queryKeys,
-  createCrudHooks,
-  postsApi,
-} from "./useApi";
-export {
-  useDeepLinking,
-  createDeepLink,
-  getDeepLinkPrefix,
-} from "./useDeepLinking";
-export { useBiometrics, getBiometricName } from "./useBiometrics";
-export { useOffline, usePendingMutations } from "./useOffline";
-export { useUpdates, getUpdateInfo, forceUpdate } from "./useUpdates";
-export {
-  usePerformance,
-  measureAsync,
-  measureSync,
-  runAfterInteractions,
-} from "./usePerformance";
-export { useMFA, generateTOTP } from "./useMFA";
-export type { MFAMethod, MFASetupData } from "./useMFA";
-export {
-  useImagePicker,
-  getFileExtension,
-  getMimeType,
-  prepareImageForUpload,
-} from "./useImagePicker";
-export type {
-  ImagePickerOptions,
-  SelectedImage,
-  UseImagePickerReturn,
-} from "./useImagePicker";
+export { useAuth, AuthProvider, getAuthToken } from "./useAuth";
+export { useTheme, ThemeProvider } from "./useTheme";
+export { useNotifications } from "./useNotifications";
+export {
+  useCurrentUser,
+  useUser,
+  useUpdateUser,
+  useSuspenseCurrentUser,
+  useSuspenseUser,
+  queryKeys,
+  createCrudHooks,
+  postsApi,
+} from "./useApi";
+export {
+  useDeepLinking,
+  createDeepLink,
+  getDeepLinkPrefix,
+} from "./useDeepLinking";
+export { useBiometrics, getBiometricName } from "./useBiometrics";
+export { useOffline, usePendingMutations } from "./useOffline";
+export { useUpdates, getUpdateInfo, forceUpdate } from "./useUpdates";
+export {
+  usePerformance,
+  measureAsync,
+  measureSync,
+  runAfterInteractions,
+} from "./usePerformance";
+export { useMFA, generateTOTP } from "./useMFA";
+export type { MFAMethod, MFASetupData } from "./useMFA";
+export {
+  useImagePicker,
+  getFileExtension,
+  getMimeType,
+  prepareImageForUpload,
+} from "./useImagePicker";
+export type {
+  UseImagePickerOptions,
+  UseImagePickerReturn,
+} from "./useImagePicker";
+export { useUpload } from "./useUpload";
+export type { UseUploadOptions, UseUploadReturn } from "./useUpload";
+export { usePermission } from "./usePermission";
+export type { UsePermissionReturn } from "./usePermission";
+export { useAnimatedEntry, useStaggeredEntry } from "./useAnimatedEntry";
+export type {
+  UseAnimatedEntryOptions,
+  UseAnimatedEntryReturn,
+  UseStaggeredEntryOptions,
+} from "./useAnimatedEntry";
+export { useParallax } from "./useParallax";
+export type { UseParallaxOptions, UseParallaxReturn } from "./useParallax";
+export { useTrackScreen } from "./useTrackScreen";
+export { useTrackEvent } from "./useTrackEvent";
+export type { UseTrackEventReturn } from "./useTrackEvent";
+export { useProducts } from "./useProducts";
+export { usePurchase } from "./usePurchase";
+export type { UsePurchaseReturn } from "./usePurchase";
+export { useSubscription } from "./useSubscription";
+export { useWebSocket } from "./useWebSocket";
+export type { UseWebSocketReturn } from "./useWebSocket";
+export { useChannel } from "./useChannel";
+export type { UseChannelReturn } from "./useChannel";
+export { usePresence } from "./usePresence";
+export type { UsePresenceReturn } from "./usePresence";
+export { useRateLimit } from "./useRateLimit";
+export { useForceUpdate } from "./useForceUpdate";
+export type { UseForceUpdateReturn } from "./useForceUpdate";
+export { useInAppReview } from "./useInAppReview";
+export { useFeatureFlag, useFeatureFlagValue } from "./useFeatureFlag";
+export { useExperiment } from "./useExperiment";