@croacroa/react-native-template 2.0.0 → 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Croacroa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,6 +2,9 @@
 
 [![npm version](https://img.shields.io/npm/v/@croacroa/react-native-template.svg)](https://www.npmjs.com/package/@croacroa/react-native-template)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
+[![Expo SDK](https://img.shields.io/badge/Expo-SDK%2052-000020.svg)](https://expo.dev/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/croacroa-dev-team/template-react-native/pulls)
 
 A production-ready React Native template with Expo SDK 52, featuring authentication, i18n, biometrics, offline support, and more.
 

package/components/providers/SuspenseBoundary.tsx

@@ -56,7 +56,7 @@ interface ErrorBoundaryProps {
  * </ErrorBoundary>
  * ```
  */
-export class ErrorBoundary extends Component<
+export class LocalErrorBoundary extends Component<
   ErrorBoundaryProps,
   ErrorBoundaryState
 > {
@@ -232,7 +232,7 @@ export function AsyncBoundary({
   fallback: loadingFallback,
 }: AsyncBoundaryProps) {
   return (
-    <ErrorBoundary
+    <LocalErrorBoundary
       key={resetKey}
       fallback={errorFallback}
       onError={onError}
@@ -246,7 +246,7 @@ export function AsyncBoundary({
       >
         {children}
       </SuspenseBoundary>
-    </ErrorBoundary>
+    </LocalErrorBoundary>
   );
 }
 
@@ -298,11 +298,11 @@ export function QueryBoundary({
   }
 
   return (
-    <ErrorBoundary fallback={errorFallback}>
+    <LocalErrorBoundary fallback={errorFallback}>
       <Suspense fallback={loadingFallback || <DefaultLoadingFallback />}>
         {children}
       </Suspense>
-    </ErrorBoundary>
+    </LocalErrorBoundary>
   );
 }
 
@@ -351,7 +351,7 @@ export function BoundaryProvider({ children }: { children: ReactNode }) {
 
   return (
     <BoundaryContext.Provider value={{ resetAll, reportError }}>
-      <ErrorBoundary key={resetKey}>{children}</ErrorBoundary>
+      <LocalErrorBoundary key={resetKey}>{children}</LocalErrorBoundary>
     </BoundaryContext.Provider>
   );
 }

package/components/providers/index.ts

@@ -1,10 +1,18 @@
 /**
  * @fileoverview Provider components for app-wide functionality
  * @module components/providers
+ *
+ * Error Boundary Usage:
+ * - Use `ErrorBoundary` (from components/ErrorBoundary) for app root with Sentry integration
+ * - Use `LocalErrorBoundary` for local async patterns (lighter, no Sentry)
  */
 
+// Main ErrorBoundary with Sentry integration - use at app root
+export { ErrorBoundary, withErrorBoundary } from "../ErrorBoundary";
+
+// Local boundaries for async patterns - lighter weight, no Sentry
 export {
-  ErrorBoundary,
+  LocalErrorBoundary,
   SuspenseBoundary,
   AsyncBoundary,
   QueryBoundary,

package/components/ui/Toast.tsx

@@ -0,0 +1,418 @@
+/**
+ * @fileoverview Custom Toast component with animations
+ * Provides a flexible toast notification system as an alternative to Burnt.
+ * @module components/ui/Toast
+ */
+
+import React, {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useRef,
+  useEffect,
+  ReactNode,
+} from "react";
+import {
+  View,
+  Text,
+  Pressable,
+  StyleSheet,
+  Dimensions,
+  AccessibilityInfo,
+} from "react-native";
+import Animated, {
+  useAnimatedStyle,
+  useSharedValue,
+  withSpring,
+  withTiming,
+  runOnJS,
+  SlideInUp,
+  SlideOutUp,
+} from "react-native-reanimated";
+import { Ionicons } from "@expo/vector-icons";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ToastType = "success" | "error" | "warning" | "info";
+
+export interface ToastConfig {
+  /** Unique identifier */
+  id: string;
+  /** Toast type determines icon and colors */
+  type: ToastType;
+  /** Main message */
+  title: string;
+  /** Optional description */
+  message?: string;
+  /** Duration in ms (0 = persistent) */
+  duration?: number;
+  /** Action button */
+  action?: {
+    label: string;
+    onPress: () => void;
+  };
+  /** Called when toast is dismissed */
+  onDismiss?: () => void;
+}
+
+interface ToastContextValue {
+  show: (config: Omit<ToastConfig, "id">) => string;
+  success: (title: string, message?: string) => string;
+  error: (title: string, message?: string) => string;
+  warning: (title: string, message?: string) => string;
+  info: (title: string, message?: string) => string;
+  dismiss: (id: string) => void;
+  dismissAll: () => void;
+}
+
+// ============================================================================
+// Context
+// ============================================================================
+
+const ToastContext = createContext<ToastContextValue | null>(null);
+
+/**
+ * Hook to access toast functions
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const toast = useToast();
+ *
+ *   const handleSave = async () => {
+ *     try {
+ *       await saveData();
+ *       toast.success("Saved!", "Your changes have been saved.");
+ *     } catch (e) {
+ *       toast.error("Error", "Failed to save changes.");
+ *     }
+ *   };
+ * }
+ * ```
+ */
+export function useToast(): ToastContextValue {
+  const context = useContext(ToastContext);
+  if (!context) {
+    throw new Error("useToast must be used within a ToastProvider");
+  }
+  return context;
+}
+
+// ============================================================================
+// Toast Item Component
+// ============================================================================
+
+const TOAST_CONFIG = {
+  success: {
+    icon: "checkmark-circle" as const,
+    bgColor: "bg-green-500",
+    iconColor: "#22c55e",
+  },
+  error: {
+    icon: "close-circle" as const,
+    bgColor: "bg-red-500",
+    iconColor: "#ef4444",
+  },
+  warning: {
+    icon: "warning" as const,
+    bgColor: "bg-amber-500",
+    iconColor: "#f59e0b",
+  },
+  info: {
+    icon: "information-circle" as const,
+    bgColor: "bg-blue-500",
+    iconColor: "#3b82f6",
+  },
+};
+
+interface ToastItemProps {
+  config: ToastConfig;
+  onDismiss: (id: string) => void;
+}
+
+function ToastItem({ config, onDismiss }: ToastItemProps) {
+  const { type, title, message, duration = 4000, action, id } = config;
+  const { icon, iconColor } = TOAST_CONFIG[type];
+  const progress = useSharedValue(1);
+  const timerRef = useRef<NodeJS.Timeout>();
+
+  useEffect(() => {
+    // Announce to screen readers
+    AccessibilityInfo.announceForAccessibility(`${type}: ${title}. ${message || ""}`);
+
+    if (duration > 0) {
+      // Start progress animation
+      progress.value = withTiming(0, { duration });
+
+      // Auto-dismiss timer
+      timerRef.current = setTimeout(() => {
+        onDismiss(id);
+      }, duration);
+    }
+
+    return () => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+      }
+    };
+  }, [duration, id, onDismiss, progress, type, title, message]);
+
+  const progressStyle = useAnimatedStyle(() => ({
+    width: `${progress.value * 100}%`,
+  }));
+
+  const handleDismiss = () => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+    }
+    config.onDismiss?.();
+    onDismiss(id);
+  };
+
+  return (
+    <Animated.View
+      entering={SlideInUp.springify().damping(15)}
+      exiting={SlideOutUp.springify().damping(15)}
+      style={styles.toastContainer}
+      accessibilityRole="alert"
+      accessibilityLiveRegion="polite"
+    >
+      <Pressable
+        onPress={handleDismiss}
+        style={styles.toastContent}
+        className="bg-white dark:bg-gray-800 rounded-2xl shadow-lg overflow-hidden"
+      >
+        {/* Icon */}
+        <View
+          className="w-10 h-10 rounded-full items-center justify-center mr-3"
+          style={{ backgroundColor: `${iconColor}20` }}
+        >
+          <Ionicons name={icon} size={24} color={iconColor} />
+        </View>
+
+        {/* Text */}
+        <View style={styles.textContainer}>
+          <Text
+            className="text-base font-semibold text-gray-900 dark:text-white"
+            numberOfLines={1}
+          >
+            {title}
+          </Text>
+          {message && (
+            <Text
+              className="text-sm text-gray-600 dark:text-gray-300 mt-0.5"
+              numberOfLines={2}
+            >
+              {message}
+            </Text>
+          )}
+        </View>
+
+        {/* Action Button */}
+        {action && (
+          <Pressable
+            onPress={() => {
+              action.onPress();
+              handleDismiss();
+            }}
+            className="ml-2 px-3 py-1.5 bg-gray-100 dark:bg-gray-700 rounded-lg"
+          >
+            <Text className="text-sm font-medium text-primary-600 dark:text-primary-400">
+              {action.label}
+            </Text>
+          </Pressable>
+        )}
+
+        {/* Close button */}
+        <Pressable
+          onPress={handleDismiss}
+          className="ml-2 p-1"
+          hitSlop={{ top: 10, bottom: 10, left: 10, right: 10 }}
+          accessibilityLabel="Dismiss notification"
+          accessibilityRole="button"
+        >
+          <Ionicons name="close" size={20} color="#9ca3af" />
+        </Pressable>
+      </Pressable>
+
+      {/* Progress bar */}
+      {duration > 0 && (
+        <View className="absolute bottom-0 left-4 right-4 h-1 bg-gray-200 dark:bg-gray-700 rounded-full overflow-hidden">
+          <Animated.View
+            style={[styles.progressBar, progressStyle, { backgroundColor: iconColor }]}
+          />
+        </View>
+      )}
+    </Animated.View>
+  );
+}
+
+// ============================================================================
+// Toast Provider
+// ============================================================================
+
+interface ToastProviderProps {
+  children: ReactNode;
+  /** Maximum number of toasts to show at once */
+  maxToasts?: number;
+}
+
+/**
+ * Toast provider component. Wrap your app with this to enable toasts.
+ *
+ * @example
+ * ```tsx
+ * export default function App() {
+ *   return (
+ *     <ToastProvider maxToasts={3}>
+ *       <NavigationContainer>
+ *         <RootNavigator />
+ *       </NavigationContainer>
+ *     </ToastProvider>
+ *   );
+ * }
+ * ```
+ */
+export function ToastProvider({ children, maxToasts = 3 }: ToastProviderProps) {
+  const [toasts, setToasts] = useState<ToastConfig[]>([]);
+  const insets = useSafeAreaInsets();
+  const idCounter = useRef(0);
+
+  const dismiss = useCallback((id: string) => {
+    setToasts((prev) => prev.filter((t) => t.id !== id));
+  }, []);
+
+  const dismissAll = useCallback(() => {
+    setToasts([]);
+  }, []);
+
+  const show = useCallback(
+    (config: Omit<ToastConfig, "id">): string => {
+      const id = `toast-${++idCounter.current}`;
+      const newToast: ToastConfig = { ...config, id };
+
+      setToasts((prev) => {
+        const updated = [newToast, ...prev];
+        // Limit number of toasts
+        return updated.slice(0, maxToasts);
+      });
+
+      return id;
+    },
+    [maxToasts]
+  );
+
+  const success = useCallback(
+    (title: string, message?: string) => show({ type: "success", title, message }),
+    [show]
+  );
+
+  const error = useCallback(
+    (title: string, message?: string) => show({ type: "error", title, message }),
+    [show]
+  );
+
+  const warning = useCallback(
+    (title: string, message?: string) => show({ type: "warning", title, message }),
+    [show]
+  );
+
+  const info = useCallback(
+    (title: string, message?: string) => show({ type: "info", title, message }),
+    [show]
+  );
+
+  return (
+    <ToastContext.Provider
+      value={{ show, success, error, warning, info, dismiss, dismissAll }}
+    >
+      {children}
+      <View
+        style={[styles.container, { top: insets.top + 8 }]}
+        pointerEvents="box-none"
+      >
+        {toasts.map((toast) => (
+          <ToastItem key={toast.id} config={toast} onDismiss={dismiss} />
+        ))}
+      </View>
+    </ToastContext.Provider>
+  );
+}
+
+// ============================================================================
+// Styles
+// ============================================================================
+
+const { width } = Dimensions.get("window");
+
+const styles = StyleSheet.create({
+  container: {
+    position: "absolute",
+    left: 16,
+    right: 16,
+    zIndex: 9999,
+    alignItems: "center",
+  },
+  toastContainer: {
+    width: width - 32,
+    marginBottom: 8,
+  },
+  toastContent: {
+    flexDirection: "row",
+    alignItems: "center",
+    padding: 12,
+    paddingBottom: 16,
+  },
+  textContainer: {
+    flex: 1,
+  },
+  progressBar: {
+    height: "100%",
+    borderRadius: 2,
+  },
+});
+
+// ============================================================================
+// Imperative API (for use outside React components)
+// ============================================================================
+
+let toastRef: ToastContextValue | null = null;
+
+export function setToastRef(ref: ToastContextValue | null) {
+  toastRef = ref;
+}
+
+/**
+ * Imperative toast API for use outside React components.
+ * Must call setToastRef first from within ToastProvider.
+ *
+ * @example
+ * ```tsx
+ * // In your root component:
+ * function App() {
+ *   const toastContext = useToast();
+ *   useEffect(() => {
+ *     setToastRef(toastContext);
+ *     return () => setToastRef(null);
+ *   }, [toastContext]);
+ *   // ...
+ * }
+ *
+ * // Then anywhere:
+ * import { toastManager } from '@/components/ui/Toast';
+ * toastManager.success('Done!');
+ * ```
+ */
+export const toastManager = {
+  show: (config: Omit<ToastConfig, "id">) => toastRef?.show(config),
+  success: (title: string, message?: string) => toastRef?.success(title, message),
+  error: (title: string, message?: string) => toastRef?.error(title, message),
+  warning: (title: string, message?: string) => toastRef?.warning(title, message),
+  info: (title: string, message?: string) => toastRef?.info(title, message),
+  dismiss: (id: string) => toastRef?.dismiss(id),
+  dismissAll: () => toastRef?.dismissAll(),
+};

package/components/ui/index.ts

@@ -21,3 +21,10 @@ export {
   VirtualizedList,
   HorizontalVirtualizedList,
 } from "./VirtualizedList";
+export {
+  ToastProvider,
+  useToast,
+  toastManager,
+  setToastRef,
+} from "./Toast";
+export type { ToastConfig, ToastType } from "./Toast";

package/hooks/index.ts

@@ -5,6 +5,8 @@ export {
   useCurrentUser,
   useUser,
   useUpdateUser,
+  useSuspenseCurrentUser,
+  useSuspenseUser,
   queryKeys,
   createCrudHooks,
   postsApi,
@@ -25,3 +27,14 @@ export {
 } 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";

package/hooks/useApi.ts

@@ -8,8 +8,10 @@ import {
   useQuery,
   useMutation,
   useQueryClient,
+  useSuspenseQuery,
   UseQueryOptions,
   UseMutationOptions,
+  UseSuspenseQueryOptions,
 } from "@tanstack/react-query";
 import { api } from "@/services/api";
 import { toast, handleApiError } from "@/utils/toast";
@@ -120,6 +122,63 @@ export function useUser(
   });
 }
 
+// ===========================================
+// Suspense-Ready Hooks (React 19 compatible)
+// ===========================================
+
+/**
+ * Suspense-ready version of useCurrentUser.
+ * Use inside a Suspense boundary - throws promise while loading.
+ *
+ * @example
+ * ```tsx
+ * function Profile() {
+ *   const { data: user } = useSuspenseCurrentUser();
+ *   // No loading check needed - Suspense handles it
+ *   return <Text>Hello, {user.name}</Text>;
+ * }
+ *
+ * // Wrap with Suspense
+ * <Suspense fallback={<Skeleton />}>
+ *   <Profile />
+ * </Suspense>
+ * ```
+ */
+export function useSuspenseCurrentUser(
+  options?: Omit<UseSuspenseQueryOptions<User, Error>, "queryKey" | "queryFn">
+) {
+  return useSuspenseQuery({
+    queryKey: queryKeys.users.me(),
+    queryFn: () => api.get<User>("/users/me"),
+    staleTime: 1000 * 60 * 5,
+    ...options,
+  });
+}
+
+/**
+ * Suspense-ready version of useUser.
+ * Use inside a Suspense boundary - throws promise while loading.
+ *
+ * @param userId - The unique identifier of the user to fetch
+ * @example
+ * ```tsx
+ * function UserCard({ userId }: { userId: string }) {
+ *   const { data: user } = useSuspenseUser(userId);
+ *   return <Avatar name={user.name} />;
+ * }
+ * ```
+ */
+export function useSuspenseUser(
+  userId: string,
+  options?: Omit<UseSuspenseQueryOptions<User, Error>, "queryKey" | "queryFn">
+) {
+  return useSuspenseQuery({
+    queryKey: queryKeys.users.detail(userId),
+    queryFn: () => api.get<User>(`/users/${userId}`),
+    ...options,
+  });
+}
+
 /**
  * Update the current user's profile.
  * Automatically updates the cache and shows a success/error toast.

package/hooks/useImagePicker.ts

@@ -0,0 +1,375 @@
+/**
+ * @fileoverview Image picker hook with permissions handling
+ * Provides a simple interface for picking images from library or camera.
+ * @module hooks/useImagePicker
+ */
+
+import { useState, useCallback } from "react";
+import * as ImagePicker from "expo-image-picker";
+import { Alert, Platform } from "react-native";
+
+/**
+ * Image picker options
+ */
+export interface ImagePickerOptions {
+  /** Allow editing/cropping the image */
+  allowsEditing?: boolean;
+  /** Aspect ratio for cropping [width, height] */
+  aspect?: [number, number];
+  /** Image quality (0-1) */
+  quality?: number;
+  /** Media types to allow */
+  mediaTypes?: ImagePicker.MediaTypeOptions;
+  /** Allow multiple selection (library only) */
+  allowsMultipleSelection?: boolean;
+  /** Maximum number of images to select */
+  selectionLimit?: number;
+  /** Base64 encode the image */
+  base64?: boolean;
+  /** Include EXIF data */
+  exif?: boolean;
+}
+
+/**
+ * Selected image result
+ */
+export interface SelectedImage {
+  uri: string;
+  width: number;
+  height: number;
+  type?: string;
+  fileName?: string;
+  fileSize?: number;
+  base64?: string;
+  exif?: Record<string, unknown>;
+}
+
+/**
+ * Hook return type
+ */
+export interface UseImagePickerReturn {
+  /** Currently selected image(s) */
+  images: SelectedImage[];
+  /** Whether an operation is in progress */
+  isLoading: boolean;
+  /** Last error that occurred */
+  error: string | null;
+  /** Pick image from library */
+  pickFromLibrary: (options?: ImagePickerOptions) => Promise<SelectedImage[] | null>;
+  /** Take photo with camera */
+  takePhoto: (options?: ImagePickerOptions) => Promise<SelectedImage | null>;
+  /** Show action sheet to choose source */
+  pickImage: (options?: ImagePickerOptions) => Promise<SelectedImage[] | null>;
+  /** Clear selected images */
+  clear: () => void;
+  /** Remove specific image by index */
+  removeImage: (index: number) => void;
+}
+
+const DEFAULT_OPTIONS: ImagePickerOptions = {
+  allowsEditing: true,
+  aspect: [1, 1],
+  quality: 0.8,
+  mediaTypes: ImagePicker.MediaTypeOptions.Images,
+  allowsMultipleSelection: false,
+  base64: false,
+  exif: false,
+};
+
+/**
+ * Convert ImagePicker asset to SelectedImage
+ */
+function assetToSelectedImage(asset: ImagePicker.ImagePickerAsset): SelectedImage {
+  return {
+    uri: asset.uri,
+    width: asset.width,
+    height: asset.height,
+    type: asset.mimeType,
+    fileName: asset.fileName ?? undefined,
+    fileSize: asset.fileSize ?? undefined,
+    base64: asset.base64 ?? undefined,
+    exif: asset.exif ?? undefined,
+  };
+}
+
+/**
+ * Hook for picking images from library or camera.
+ * Handles permissions automatically and provides a clean API.
+ *
+ * @example
+ * ```tsx
+ * function AvatarPicker() {
+ *   const { images, pickImage, isLoading } = useImagePicker();
+ *
+ *   return (
+ *     <Pressable onPress={() => pickImage({ aspect: [1, 1] })}>
+ *       {images[0] ? (
+ *         <Image source={{ uri: images[0].uri }} style={styles.avatar} />
+ *       ) : (
+ *         <Text>Select Avatar</Text>
+ *       )}
+ *     </Pressable>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple image selection
+ * function GalleryPicker() {
+ *   const { images, pickFromLibrary, removeImage } = useImagePicker();
+ *
+ *   const handlePick = () => {
+ *     pickFromLibrary({
+ *       allowsMultipleSelection: true,
+ *       selectionLimit: 5,
+ *     });
+ *   };
+ *
+ *   return (
+ *     <View>
+ *       <Button onPress={handlePick}>Add Photos</Button>
+ *       {images.map((img, i) => (
+ *         <ImageThumb key={i} uri={img.uri} onRemove={() => removeImage(i)} />
+ *       ))}
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useImagePicker(): UseImagePickerReturn {
+  const [images, setImages] = useState<SelectedImage[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  /**
+   * Request camera permissions
+   */
+  const requestCameraPermission = useCallback(async (): Promise<boolean> => {
+    const { status } = await ImagePicker.requestCameraPermissionsAsync();
+    if (status !== "granted") {
+      Alert.alert(
+        "Camera Permission Required",
+        "Please allow camera access in your device settings to take photos.",
+        [{ text: "OK" }]
+      );
+      return false;
+    }
+    return true;
+  }, []);
+
+  /**
+   * Request media library permissions
+   */
+  const requestLibraryPermission = useCallback(async (): Promise<boolean> => {
+    const { status } = await ImagePicker.requestMediaLibraryPermissionsAsync();
+    if (status !== "granted") {
+      Alert.alert(
+        "Photo Library Permission Required",
+        "Please allow photo library access in your device settings to select images.",
+        [{ text: "OK" }]
+      );
+      return false;
+    }
+    return true;
+  }, []);
+
+  /**
+   * Pick image from library
+   */
+  const pickFromLibrary = useCallback(
+    async (options: ImagePickerOptions = {}): Promise<SelectedImage[] | null> => {
+      setError(null);
+      setIsLoading(true);
+
+      try {
+        const hasPermission = await requestLibraryPermission();
+        if (!hasPermission) {
+          return null;
+        }
+
+        const mergedOptions = { ...DEFAULT_OPTIONS, ...options };
+
+        const result = await ImagePicker.launchImageLibraryAsync({
+          mediaTypes: mergedOptions.mediaTypes,
+          allowsEditing: mergedOptions.allowsMultipleSelection
+            ? false
+            : mergedOptions.allowsEditing,
+          aspect: mergedOptions.aspect,
+          quality: mergedOptions.quality,
+          allowsMultipleSelection: mergedOptions.allowsMultipleSelection,
+          selectionLimit: mergedOptions.selectionLimit,
+          base64: mergedOptions.base64,
+          exif: mergedOptions.exif,
+        });
+
+        if (result.canceled) {
+          return null;
+        }
+
+        const selectedImages = result.assets.map(assetToSelectedImage);
+
+        if (mergedOptions.allowsMultipleSelection) {
+          setImages((prev) => [...prev, ...selectedImages]);
+        } else {
+          setImages(selectedImages);
+        }
+
+        return selectedImages;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Failed to pick image";
+        setError(message);
+        console.error("[useImagePicker] Library error:", err);
+        return null;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [requestLibraryPermission]
+  );
+
+  /**
+   * Take photo with camera
+   */
+  const takePhoto = useCallback(
+    async (options: ImagePickerOptions = {}): Promise<SelectedImage | null> => {
+      setError(null);
+      setIsLoading(true);
+
+      try {
+        const hasPermission = await requestCameraPermission();
+        if (!hasPermission) {
+          return null;
+        }
+
+        const mergedOptions = { ...DEFAULT_OPTIONS, ...options };
+
+        const result = await ImagePicker.launchCameraAsync({
+          mediaTypes: mergedOptions.mediaTypes,
+          allowsEditing: mergedOptions.allowsEditing,
+          aspect: mergedOptions.aspect,
+          quality: mergedOptions.quality,
+          base64: mergedOptions.base64,
+          exif: mergedOptions.exif,
+        });
+
+        if (result.canceled) {
+          return null;
+        }
+
+        const selectedImage = assetToSelectedImage(result.assets[0]);
+        setImages([selectedImage]);
+
+        return selectedImage;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Failed to take photo";
+        setError(message);
+        console.error("[useImagePicker] Camera error:", err);
+        return null;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [requestCameraPermission]
+  );
+
+  /**
+   * Show action sheet to choose source (library or camera)
+   */
+  const pickImage = useCallback(
+    async (options: ImagePickerOptions = {}): Promise<SelectedImage[] | null> => {
+      return new Promise((resolve) => {
+        Alert.alert("Select Image", "Choose image source", [
+          {
+            text: "Camera",
+            onPress: async () => {
+              const result = await takePhoto(options);
+              resolve(result ? [result] : null);
+            },
+          },
+          {
+            text: "Photo Library",
+            onPress: async () => {
+              const result = await pickFromLibrary(options);
+              resolve(result);
+            },
+          },
+          {
+            text: "Cancel",
+            style: "cancel",
+            onPress: () => resolve(null),
+          },
+        ]);
+      });
+    },
+    [takePhoto, pickFromLibrary]
+  );
+
+  /**
+   * Clear all selected images
+   */
+  const clear = useCallback(() => {
+    setImages([]);
+    setError(null);
+  }, []);
+
+  /**
+   * Remove image by index
+   */
+  const removeImage = useCallback((index: number) => {
+    setImages((prev) => prev.filter((_, i) => i !== index));
+  }, []);
+
+  return {
+    images,
+    isLoading,
+    error,
+    pickFromLibrary,
+    takePhoto,
+    pickImage,
+    clear,
+    removeImage,
+  };
+}
+
+/**
+ * Utility to get file extension from URI
+ */
+export function getFileExtension(uri: string): string {
+  const match = uri.match(/\.(\w+)$/);
+  return match ? match[1].toLowerCase() : "jpg";
+}
+
+/**
+ * Utility to get MIME type from extension
+ */
+export function getMimeType(extension: string): string {
+  const mimeTypes: Record<string, string> = {
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    gif: "image/gif",
+    webp: "image/webp",
+    heic: "image/heic",
+    heif: "image/heif",
+  };
+  return mimeTypes[extension.toLowerCase()] || "image/jpeg";
+}
+
+/**
+ * Prepare image for FormData upload
+ */
+export function prepareImageForUpload(
+  image: SelectedImage,
+  fieldName = "image"
+): { uri: string; type: string; name: string } {
+  const extension = getFileExtension(image.uri);
+  const type = image.type || getMimeType(extension);
+  const name = image.fileName || `${fieldName}.${extension}`;
+
+  return {
+    uri: Platform.OS === "ios" ? image.uri.replace("file://", "") : image.uri,
+    type,
+    name,
+  };
+}

package/hooks/useOffline.ts

@@ -4,7 +4,7 @@
  * @module hooks/useOffline
  */
 
-import { useEffect, useState } from "react";
+import { useEffect, useState, useCallback } from "react";
 import NetInfo, { NetInfoState } from "@react-native-community/netinfo";
 import { onlineManager } from "@tanstack/react-query";
 import { toast } from "@/utils/toast";
@@ -68,9 +68,10 @@ export function useOffline(options: UseOfflineOptions = {}) {
 
 /**
  * Hook for tracking pending mutations count.
- * Useful to show a sync indicator when there are queued offline mutations.
+ * Integrates with the backgroundSync mutation queue.
  *
- * @returns Object with pendingCount and hasPending flag
+ * @param pollingInterval - How often to check the queue (default: 5000ms)
+ * @returns Object with pendingCount, hasPending flag, and refresh function
  *
  * @example
  * ```tsx
@@ -87,13 +88,36 @@ export function useOffline(options: UseOfflineOptions = {}) {
  * }
  * ```
  */
-export function usePendingMutations() {
+export function usePendingMutations(pollingInterval = 5000) {
   const [pendingCount, setPendingCount] = useState(0);
+  const [isLoading, setIsLoading] = useState(true);
+
+  const refresh = useCallback(async () => {
+    try {
+      const { getMutationQueue } = await import("@/services/backgroundSync");
+      const queue = await getMutationQueue();
+      setPendingCount(queue.length);
+    } catch (error) {
+      console.error("[usePendingMutations] Failed to get queue:", error);
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    // Initial fetch
+    refresh();
+
+    // Poll for updates
+    const interval = setInterval(refresh, pollingInterval);
+
+    return () => clearInterval(interval);
+  }, [refresh, pollingInterval]);
 
-  // This would need to be integrated with mutation cache
-  // For now, return 0 as a placeholder
   return {
     pendingCount,
     hasPending: pendingCount > 0,
+    isLoading,
+    refresh,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@croacroa/react-native-template",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Production-ready React Native template with Expo, authentication, i18n, offline support, and more",
   "main": "expo-router/entry",
   "author": "Croacroa <contact@croacroa.dev>",
@@ -75,6 +75,7 @@
     "expo-device": "~7.0.1",
     "expo-font": "~13.0.2",
     "expo-image": "~2.0.4",
+    "expo-image-picker": "^17.0.10",
     "expo-linking": "~7.0.4",
     "expo-local-authentication": "~15.0.1",
     "expo-localization": "~16.0.0",

package/services/security.ts

@@ -199,6 +199,9 @@ export const SSL_PINNING_CONFIG = {
 
   /**
    * Generate Android network_security_config.xml content
+   * Save this to android/app/src/main/res/xml/network_security_config.xml
+   * and reference it in AndroidManifest.xml:
+   * <application android:networkSecurityConfig="@xml/network_security_config">
    */
   getAndroidConfig(): string {
     const pinEntries = Object.entries(SECURITY.SSL_PINS)
@@ -209,7 +212,7 @@ export const SSL_PINNING_CONFIG = {
 
         return `    <domain-config cleartextTrafficPermitted="false">
       <domain includeSubdomains="true">${domain}</domain>
-      <pin-set expiration="2025-12-31">
+      <pin-set expiration="2026-12-31">
 ${pinElements}
       </pin-set>
     </domain-config>`;
@@ -226,4 +229,58 @@ ${pinElements}
 ${pinEntries}
 </network-security-config>`;
   },
+
+  /**
+   * Generate iOS TrustKit configuration dictionary
+   * Add this to your AppDelegate.mm or use expo-build-properties plugin
+   *
+   * For Expo managed workflow, add to app.config.ts:
+   * ```
+   * plugins: [
+   *   ["expo-build-properties", {
+   *     ios: {
+   *       infoPlist: SSL_PINNING_CONFIG.getIOSInfoPlist()
+   *     }
+   *   }]
+   * ]
+   * ```
+   */
+  getIOSConfig(): Record<string, unknown> {
+    const pinnedDomains: Record<string, unknown> = {};
+
+    Object.entries(SECURITY.SSL_PINS).forEach(([domain, pins]) => {
+      pinnedDomains[domain] = {
+        TSKIncludeSubdomains: true,
+        TSKEnforcePinning: true,
+        TSKPublicKeyHashes: pins.map((pin) => pin.replace("sha256/", "")),
+      };
+    });
+
+    return {
+      TSKSwizzleNetworkDelegates: true,
+      TSKPinnedDomains: pinnedDomains,
+    };
+  },
+
+  /**
+   * Generate iOS Info.plist entries for SSL pinning
+   */
+  getIOSInfoPlist(): Record<string, unknown> {
+    return {
+      NSAppTransportSecurity: {
+        NSAllowsArbitraryLoads: false,
+        NSPinnedDomains: Object.fromEntries(
+          Object.entries(SECURITY.SSL_PINS).map(([domain, pins]) => [
+            domain,
+            {
+              NSIncludesSubdomains: true,
+              NSPinnedLeafIdentities: pins.map((pin) => ({
+                "SPKI-SHA256-BASE64": pin.replace("sha256/", ""),
+              })),
+            },
+          ])
+        ),
+      },
+    };
+  },
 };

package/utils/validation.ts

@@ -12,7 +12,8 @@ export const passwordSchema = z
   .min(8, "Password must be at least 8 characters")
   .regex(/[A-Z]/, "Password must contain at least one uppercase letter")
   .regex(/[a-z]/, "Password must contain at least one lowercase letter")
-  .regex(/[0-9]/, "Password must contain at least one number");
+  .regex(/[0-9]/, "Password must contain at least one number")
+  .regex(/[!@#$%^&*()_+\-=\[\]{};':"\\|,.<>\/?]/, "Password must contain at least one special character");
 
 export const nameSchema = z
   .string()