@croacroa/react-native-template 2.0.1 → 3.2.0

package/hooks/useFeatureFlag.ts

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview React hooks for feature flag evaluation
+ * Provides `useFeatureFlag` for boolean checks and `useFeatureFlagValue`
+ * for typed flag values, both backed by the FeatureFlags facade.
+ * @module hooks/useFeatureFlag
+ */
+
+import { useState, useEffect } from "react";
+import { FeatureFlags } from "@/services/feature-flags/feature-flag-adapter";
+
+/**
+ * Hook that resolves a boolean feature flag.
+ *
+ * @param flag - The flag key to evaluate
+ * @param defaultValue - Value used until the flag is resolved (default `false`)
+ * @returns `{ isEnabled, isLoading }`
+ *
+ * @example
+ * ```tsx
+ * const { isEnabled, isLoading } = useFeatureFlag("new_checkout");
+ * if (isLoading) return <Loader />;
+ * return isEnabled ? <NewCheckout /> : <OldCheckout />;
+ * ```
+ */
+export function useFeatureFlag(flag: string, defaultValue = false) {
+  const [isEnabled, setIsEnabled] = useState(defaultValue);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    setIsEnabled(FeatureFlags.isEnabled(flag, defaultValue));
+    setIsLoading(false);
+  }, [flag, defaultValue]);
+
+  return { isEnabled, isLoading };
+}
+
+/**
+ * Hook that resolves a feature flag with an arbitrary type.
+ *
+ * @param flag - The flag key to evaluate
+ * @param defaultValue - Value used until the flag is resolved
+ * @returns `{ value, isLoading }`
+ *
+ * @example
+ * ```tsx
+ * const { value: maxItems } = useFeatureFlagValue("max_cart_items", 10);
+ * ```
+ */
+export function useFeatureFlagValue<T>(flag: string, defaultValue: T) {
+  const [value, setValue] = useState<T>(defaultValue);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    setValue(FeatureFlags.getValue(flag, defaultValue));
+    setIsLoading(false);
+  }, [flag, defaultValue]);
+
+  return { value, isLoading };
+}

package/hooks/useForceUpdate.ts

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview Hook for app force-update checks
+ * Checks on mount whether the running app version satisfies the server's
+ * minimum version requirement and exposes the result to the UI.
+ * @module hooks/useForceUpdate
+ */
+
+import { useEffect, useState } from "react";
+import Constants from "expo-constants";
+
+import { FORCE_UPDATE } from "@/constants/config";
+import { checkForUpdate } from "@/services/force-update";
+import type { ForceUpdateResult } from "@/services/force-update";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface UseForceUpdateReturn extends ForceUpdateResult {
+  /** Whether the check is still in progress */
+  isChecking: boolean;
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Check on mount whether the app requires a mandatory native update.
+ *
+ * Uses `Constants.expoConfig?.version` as the current version and the
+ * `FORCE_UPDATE` configuration from `constants/config.ts`.
+ *
+ * When `FORCE_UPDATE.ENABLED` is `false` or `FORCE_UPDATE.CHECK_URL` is
+ * empty the hook returns immediately with `isUpdateRequired: false`.
+ *
+ * @returns Force-update state including loading indicator
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { isUpdateRequired, isChecking, storeUrl, currentVersion, minimumVersion } =
+ *     useForceUpdate();
+ *
+ *   if (isChecking) return <SplashScreen />;
+ *
+ *   if (isUpdateRequired) {
+ *     return (
+ *       <ForceUpdateScreen
+ *         storeUrl={storeUrl}
+ *         currentVersion={currentVersion}
+ *         minimumVersion={minimumVersion}
+ *       />
+ *     );
+ *   }
+ *
+ *   return <MainApp />;
+ * }
+ * ```
+ */
+export function useForceUpdate(): UseForceUpdateReturn {
+  const [isChecking, setIsChecking] = useState(true);
+  const [result, setResult] = useState<ForceUpdateResult>({
+    isUpdateRequired: false,
+    currentVersion: "",
+    minimumVersion: "",
+    storeUrl: "",
+  });
+
+  useEffect(() => {
+    // Skip the check entirely when force-update is disabled or unconfigured
+    if (!FORCE_UPDATE.ENABLED || !FORCE_UPDATE.CHECK_URL) {
+      setIsChecking(false);
+      return;
+    }
+
+    const currentVersion = Constants.expoConfig?.version ?? "1.0.0";
+
+    checkForUpdate({
+      checkUrl: FORCE_UPDATE.CHECK_URL,
+      currentVersion,
+    })
+      .then(setResult)
+      .finally(() => setIsChecking(false));
+  }, []);
+
+  return {
+    ...result,
+    isChecking,
+  };
+}

package/hooks/useImagePicker.ts

@@ -0,0 +1,281 @@
+/**
+ * @fileoverview Combined image pick, compress, and preview hook
+ * Integrates media picker and compression services with permission management.
+ * @module hooks/useImagePicker
+ */
+
+import { useState, useCallback } from "react";
+import { Alert, Platform } from "react-native";
+
+import { usePermission } from "@/hooks/usePermission";
+import {
+  pickFromLibrary as pickFromLib,
+  pickFromCamera as pickFromCam,
+  type PickedMedia,
+} from "@/services/media/media-picker";
+import { compressImage } from "@/services/media/compression";
+
+/**
+ * Options for the useImagePicker hook
+ */
+export interface UseImagePickerOptions {
+  /** Whether to compress images after picking (default: true) */
+  compress?: boolean;
+  /** Maximum width for compression (default: 1080) */
+  maxWidth?: number;
+  /** Maximum height for compression (default: 1080) */
+  maxHeight?: number;
+  /** Compression quality 0-1 (default: 0.7) */
+  quality?: number;
+}
+
+/**
+ * Return type for the useImagePicker hook
+ */
+export interface UseImagePickerReturn {
+  /** Pick media from the photo library */
+  pickFromLibrary: () => Promise<PickedMedia | null>;
+  /** Take a photo with the camera */
+  pickFromCamera: () => Promise<PickedMedia | null>;
+  /** Currently selected media item */
+  selectedMedia: PickedMedia | null;
+  /** Whether a pick or compress operation is in progress */
+  isLoading: boolean;
+  /** Clear the selected media */
+  clear: () => void;
+  /** Camera permission state from usePermission */
+  cameraPermission: ReturnType<typeof usePermission>;
+  /** Media library permission state from usePermission */
+  mediaLibraryPermission: ReturnType<typeof usePermission>;
+}
+
+/**
+ * Hook for picking, compressing, and previewing images.
+ * Combines the media picker service with compression and centralized
+ * permission management via usePermission.
+ *
+ * @param options - Configuration for compression and behavior
+ * @returns Pick functions, selected media state, and permission info
+ *
+ * @example
+ * ```tsx
+ * function ProfilePhoto() {
+ *   const { pickFromLibrary, pickFromCamera, selectedMedia, isLoading, clear } =
+ *     useImagePicker({ maxWidth: 500, quality: 0.8 });
+ *
+ *   return (
+ *     <View>
+ *       {selectedMedia ? (
+ *         <>
+ *           <Image source={{ uri: selectedMedia.uri }} style={{ width: 200, height: 200 }} />
+ *           <Button onPress={clear}>Remove</Button>
+ *         </>
+ *       ) : (
+ *         <>
+ *           <Button onPress={pickFromLibrary}>Choose Photo</Button>
+ *           <Button onPress={pickFromCamera}>Take Photo</Button>
+ *         </>
+ *       )}
+ *       {isLoading && <ActivityIndicator />}
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useImagePicker(
+  options: UseImagePickerOptions = {}
+): UseImagePickerReturn {
+  const {
+    compress = true,
+    maxWidth = 1080,
+    maxHeight = 1080,
+    quality = 0.7,
+  } = options;
+
+  const [selectedMedia, setSelectedMedia] = useState<PickedMedia | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+
+  const cameraPermission = usePermission("camera");
+  const mediaLibraryPermission = usePermission("mediaLibrary");
+
+  /**
+   * Ensure a permission is granted, requesting it if needed
+   */
+  const ensurePermission = useCallback(
+    async (
+      permission: ReturnType<typeof usePermission>,
+      label: string
+    ): Promise<boolean> => {
+      if (permission.isGranted) {
+        return true;
+      }
+
+      if (permission.isBlocked) {
+        Alert.alert(
+          `${label} Permission Required`,
+          `Please allow ${label.toLowerCase()} access in your device settings.`,
+          [
+            { text: "Cancel", style: "cancel" },
+            { text: "Open Settings", onPress: () => permission.openSettings() },
+          ]
+        );
+        return false;
+      }
+
+      // Request the permission and use the returned status directly
+      // to avoid reading stale React state after an async operation.
+      const resultStatus = await permission.request();
+      return resultStatus === "granted";
+    },
+    []
+  );
+
+  /**
+   * Optionally compress a picked image
+   */
+  const maybeCompress = useCallback(
+    async (media: PickedMedia): Promise<PickedMedia> => {
+      if (!compress || media.type !== "image") {
+        return media;
+      }
+
+      try {
+        const result = await compressImage(media.uri, {
+          maxWidth,
+          maxHeight,
+          quality,
+        });
+
+        return {
+          ...media,
+          uri: result.uri,
+          width: result.width,
+          height: result.height,
+        };
+      } catch (err) {
+        console.warn(
+          "[useImagePicker] Compression failed, using original:",
+          err
+        );
+        return media;
+      }
+    },
+    [compress, maxWidth, maxHeight, quality]
+  );
+
+  /**
+   * Pick media from the photo library
+   */
+  const pickFromLibrary = useCallback(async (): Promise<PickedMedia | null> => {
+    setIsLoading(true);
+    try {
+      const hasPermission = await ensurePermission(
+        mediaLibraryPermission,
+        "Photo Library"
+      );
+      if (!hasPermission) {
+        return null;
+      }
+
+      const items = await pickFromLib({ quality: 0.8 });
+      if (items.length === 0) {
+        return null;
+      }
+
+      const compressed = await maybeCompress(items[0]);
+      setSelectedMedia(compressed);
+      return compressed;
+    } catch (err) {
+      console.error("[useImagePicker] Library pick error:", err);
+      return null;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [ensurePermission, mediaLibraryPermission, maybeCompress]);
+
+  /**
+   * Take a photo with the camera
+   */
+  const pickFromCamera = useCallback(async (): Promise<PickedMedia | null> => {
+    setIsLoading(true);
+    try {
+      const hasPermission = await ensurePermission(cameraPermission, "Camera");
+      if (!hasPermission) {
+        return null;
+      }
+
+      const item = await pickFromCam({ quality: 0.8 });
+      if (!item) {
+        return null;
+      }
+
+      const compressed = await maybeCompress(item);
+      setSelectedMedia(compressed);
+      return compressed;
+    } catch (err) {
+      console.error("[useImagePicker] Camera pick error:", err);
+      return null;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [ensurePermission, cameraPermission, maybeCompress]);
+
+  /**
+   * Clear the selected media
+   */
+  const clear = useCallback(() => {
+    setSelectedMedia(null);
+  }, []);
+
+  return {
+    pickFromLibrary,
+    pickFromCamera,
+    selectedMedia,
+    isLoading,
+    clear,
+    cameraPermission,
+    mediaLibraryPermission,
+  };
+}
+
+/**
+ * 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(
+  media: PickedMedia,
+  fieldName = "image"
+): { uri: string; type: string; name: string } {
+  const extension = getFileExtension(media.uri);
+  const type = getMimeType(extension);
+  const name = media.fileName || `${fieldName}.${extension}`;
+
+  return {
+    uri: Platform.OS === "ios" ? media.uri.replace("file://", "") : media.uri,
+    type,
+    name,
+  };
+}

package/hooks/useInAppReview.ts

@@ -0,0 +1,64 @@
+import { useState, useCallback, useEffect } from "react";
+import * as StoreReview from "expo-store-review";
+import { storage } from "@/services/storage";
+import { IN_APP_REVIEW } from "@/constants/config";
+import { useAppStore } from "@/stores/appStore";
+
+const LAST_REVIEW_PROMPT_DATE_KEY = "LAST_REVIEW_PROMPT_DATE";
+
+interface UseInAppReviewReturn {
+  requestReview: () => Promise<void>;
+  isAvailable: boolean;
+  hasRequested: boolean;
+}
+
+/**
+ * Hook for requesting in-app reviews with throttling and session gating.
+ *
+ * - Won't show if fewer than MIN_SESSIONS sessions have occurred
+ * - Won't show if the last prompt was less than DAYS_BETWEEN_PROMPTS days ago
+ * - Tracks whether a review was requested in this session
+ */
+export function useInAppReview(): UseInAppReviewReturn {
+  const [isAvailable, setIsAvailable] = useState(false);
+  const [hasRequested, setHasRequested] = useState(false);
+  const sessionCount = useAppStore((s) => s.sessionCount);
+
+  useEffect(() => {
+    StoreReview.isAvailableAsync()
+      .then(setIsAvailable)
+      .catch(() => setIsAvailable(false));
+  }, []);
+
+  const requestReview = useCallback(async () => {
+    // Already requested this session
+    if (hasRequested) return;
+
+    // Platform doesn't support in-app review
+    if (!isAvailable) return;
+
+    // Not enough sessions yet
+    if (sessionCount < IN_APP_REVIEW.MIN_SESSIONS) return;
+
+    // Check throttle window
+    const lastPromptDate = await storage.get<string>(
+      LAST_REVIEW_PROMPT_DATE_KEY
+    );
+    if (lastPromptDate) {
+      const daysSinceLastPrompt =
+        (Date.now() - new Date(lastPromptDate).getTime()) /
+        (1000 * 60 * 60 * 24);
+      if (daysSinceLastPrompt < IN_APP_REVIEW.DAYS_BETWEEN_PROMPTS) return;
+    }
+
+    try {
+      await StoreReview.requestReview();
+      setHasRequested(true);
+      await storage.set(LAST_REVIEW_PROMPT_DATE_KEY, new Date().toISOString());
+    } catch (error) {
+      console.error("Failed to request in-app review:", error);
+    }
+  }, [hasRequested, isAvailable, sessionCount]);
+
+  return { requestReview, isAvailable, hasRequested };
+}