@croacroa/react-native-template 2.0.1 → 3.2.0

package/hooks/useUpload.ts

@@ -0,0 +1,165 @@
+/**
+ * @fileoverview Upload hook with progress tracking, cancellation, and retry
+ * Wraps the media-upload service in a React hook with state management.
+ * @module hooks/useUpload
+ */
+
+import { useState, useCallback, useRef } from "react";
+
+import {
+  uploadFile,
+  type UploadProgress,
+  type UploadResult,
+} from "@/services/media/media-upload";
+
+/**
+ * Options for the useUpload hook
+ */
+export interface UseUploadOptions {
+  /** Server URL to upload to */
+  url: string;
+  /** Additional HTTP headers */
+  headers?: Record<string, string>;
+  /** Form field name for the file (default: 'file') */
+  fieldName?: string;
+}
+
+/**
+ * Return type for the useUpload hook
+ */
+export interface UseUploadReturn {
+  /** Start an upload */
+  upload: (
+    uri: string,
+    extraFields?: Record<string, string>
+  ) => Promise<UploadResult | null>;
+  /** Current upload progress */
+  progress: UploadProgress | null;
+  /** Whether an upload is in progress */
+  isUploading: boolean;
+  /** Last upload error */
+  error: string | null;
+  /** Cancel the current upload */
+  cancel: () => void;
+  /** Reset all state */
+  reset: () => void;
+}
+
+/**
+ * Hook for uploading files with progress tracking, cancellation, and retry support.
+ *
+ * @param options - Upload configuration
+ * @returns Upload function, progress state, and control functions
+ *
+ * @example
+ * ```tsx
+ * function UploadScreen() {
+ *   const { upload, progress, isUploading, error, cancel, reset } = useUpload({
+ *     url: 'https://api.example.com/upload',
+ *     headers: { Authorization: `Bearer ${token}` },
+ *   });
+ *
+ *   const handleUpload = async (uri: string) => {
+ *     const result = await upload(uri, { userId: '123' });
+ *     if (result) {
+ *       console.log('Upload complete:', result.status);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <View>
+ *       {isUploading && (
+ *         <>
+ *           <Text>Uploading... {progress?.percentage ?? 0}%</Text>
+ *           <Button onPress={cancel}>Cancel</Button>
+ *         </>
+ *       )}
+ *       {error && (
+ *         <>
+ *           <Text>{error}</Text>
+ *           <Button onPress={() => handleUpload(lastUri)}>Retry</Button>
+ *         </>
+ *       )}
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useUpload(options: UseUploadOptions): UseUploadReturn {
+  const { url, headers, fieldName = "file" } = options;
+
+  const [progress, setProgress] = useState<UploadProgress | null>(null);
+  const [isUploading, setIsUploading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const abortRef = useRef<(() => void) | null>(null);
+
+  /**
+   * Start uploading a file
+   */
+  const upload = useCallback(
+    async (
+      uri: string,
+      extraFields?: Record<string, string>
+    ): Promise<UploadResult | null> => {
+      setError(null);
+      setProgress(null);
+      setIsUploading(true);
+
+      try {
+        const { promise, abort } = uploadFile({
+          url,
+          uri,
+          fieldName,
+          headers,
+          extraFields,
+          onProgress: (p) => {
+            setProgress(p);
+          },
+        });
+
+        abortRef.current = abort;
+
+        const result = await promise;
+        return result;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Upload failed";
+        setError(message);
+        return null;
+      } finally {
+        abortRef.current = null;
+        setIsUploading(false);
+      }
+    },
+    [url, headers, fieldName]
+  );
+
+  /**
+   * Cancel the current upload
+   */
+  const cancel = useCallback(() => {
+    if (abortRef.current) {
+      abortRef.current();
+      abortRef.current = null;
+    }
+  }, []);
+
+  /**
+   * Reset all state
+   */
+  const reset = useCallback(() => {
+    cancel();
+    setProgress(null);
+    setIsUploading(false);
+    setError(null);
+  }, [cancel]);
+
+  return {
+    upload,
+    progress,
+    isUploading,
+    error,
+    cancel,
+    reset,
+  };
+}

package/hooks/useWebSocket.ts

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview WebSocket connection lifecycle hook
+ * Manages a WebSocketManager instance with auto-connect on mount
+ * and clean disconnect on unmount.
+ * @module hooks/useWebSocket
+ */
+
+import { useEffect, useRef, useState, useCallback } from "react";
+
+import { WebSocketManager } from "@/services/realtime/websocket-manager";
+import type {
+  ConnectionStatus,
+  WebSocketConfig,
+} from "@/services/realtime/types";
+
+/**
+ * Return type for the useWebSocket hook.
+ */
+export interface UseWebSocketReturn {
+  /** Current connection status */
+  status: ConnectionStatus;
+  /** Send a typed message over the WebSocket */
+  send: <T = unknown>(type: string, payload: T, channel?: string) => void;
+  /** Manually open the WebSocket connection */
+  connect: () => Promise<void>;
+  /** Manually close the WebSocket connection */
+  disconnect: () => void;
+  /** The underlying WebSocketManager instance */
+  manager: WebSocketManager;
+}
+
+/**
+ * Hook for managing a WebSocket connection lifecycle.
+ *
+ * Creates a single `WebSocketManager` instance (persisted across re-renders via ref),
+ * connects on mount, and disconnects on unmount. Tracks the connection status
+ * in React state so the component re-renders on status changes.
+ *
+ * @param config - WebSocket configuration (url, auth, reconnect settings)
+ * @returns Object with status, send, connect, disconnect, and the manager instance
+ *
+ * @example
+ * ```tsx
+ * function ChatScreen() {
+ *   const { status, send, manager } = useWebSocket({
+ *     url: 'wss://api.example.com/ws',
+ *     getToken: async () => authStore.getState().token,
+ *   });
+ *
+ *   const handleSend = () => {
+ *     send('chat:message', { text: 'Hello!' }, 'room-1');
+ *   };
+ *
+ *   return (
+ *     <View>
+ *       <Text>Status: {status}</Text>
+ *       <Button onPress={handleSend} title="Send" />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useWebSocket(config: WebSocketConfig): UseWebSocketReturn {
+  const managerRef = useRef<WebSocketManager | null>(null);
+  const [status, setStatus] = useState<ConnectionStatus>("disconnected");
+
+  // Create the manager once and keep it stable across re-renders
+  if (!managerRef.current) {
+    managerRef.current = new WebSocketManager(config);
+  }
+
+  const manager = managerRef.current;
+
+  useEffect(() => {
+    // Subscribe to status changes
+    const unsubscribe = manager.onStatusChange((newStatus) => {
+      setStatus(newStatus);
+    });
+
+    // Auto-connect on mount
+    manager.connect();
+
+    return () => {
+      unsubscribe();
+      manager.disconnect();
+    };
+  }, [manager]);
+
+  const send = useCallback(
+    <T = unknown>(type: string, payload: T, channel?: string) => {
+      manager.send(type, payload, channel);
+    },
+    [manager]
+  );
+
+  const connect = useCallback(async () => {
+    await manager.connect();
+  }, [manager]);
+
+  const disconnect = useCallback(() => {
+    manager.disconnect();
+  }, [manager]);
+
+  return {
+    status,
+    send,
+    connect,
+    disconnect,
+    manager,
+  };
+}

package/i18n/index.ts

@@ -1,194 +1,197 @@
-/**
- * @fileoverview Internationalization (i18n) setup with RTL support
- * Provides multi-language support with automatic device language detection.
- * @module i18n
- */
-
-import i18n from "i18next";
-import { initReactI18next } from "react-i18next";
-import * as Localization from "expo-localization";
-import { I18nManager } from "react-native";
-import { storage } from "@/services/storage";
-
-import en from "./locales/en.json";
-import fr from "./locales/fr.json";
-import es from "./locales/es.json";
-import de from "./locales/de.json";
-import ar from "./locales/ar.json";
-
-/**
- * Supported languages configuration.
- * Each language includes its English name, native name, and RTL flag.
- */
-export const LANGUAGES = {
-  en: { name: "English", nativeName: "English", rtl: false },
-  fr: { name: "French", nativeName: "Français", rtl: false },
-  es: { name: "Spanish", nativeName: "Español", rtl: false },
-  de: { name: "German", nativeName: "Deutsch", rtl: false },
-  ar: { name: "Arabic", nativeName: "العربية", rtl: true },
-} as const;
-
-export type LanguageCode = keyof typeof LANGUAGES;
-
-const LANGUAGE_STORAGE_KEY = "app_language";
-
-const resources = {
-  en: { translation: en },
-  fr: { translation: fr },
-  es: { translation: es },
-  de: { translation: de },
-  ar: { translation: ar },
-};
-
-/**
- * Get the device's preferred language
- * Falls back to 'en' if not supported
- */
-function getDeviceLanguage(): LanguageCode {
-  const locale = Localization.getLocales()[0];
-  const languageCode = locale?.languageCode || "en";
-
-  // Check if we support this language
-  if (languageCode in LANGUAGES) {
-    return languageCode as LanguageCode;
-  }
-
-  return "en";
-}
-
-/**
- * Initialize i18n with the saved language or device language
- */
-export async function initI18n(): Promise<void> {
-  // Try to get saved language preference
-  const savedLanguage = await storage.get<LanguageCode>(LANGUAGE_STORAGE_KEY);
-  const initialLanguage = savedLanguage || getDeviceLanguage();
-
-  await i18n.use(initReactI18next).init({
-    resources,
-    lng: initialLanguage,
-    fallbackLng: "en",
-    compatibilityJSON: "v3",
-    interpolation: {
-      escapeValue: false, // React already escapes values
-    },
-    react: {
-      useSuspense: false, // Prevents issues with SSR/async loading
-    },
-  });
-}
-
-/**
- * Change the app language and apply RTL settings if needed.
- * Note: RTL changes require an app restart to take full effect.
- *
- * @param language - The language code to switch to
- * @returns Promise that resolves when the language is changed
- */
-export async function changeLanguage(language: LanguageCode): Promise<void> {
-  await i18n.changeLanguage(language);
-  await storage.set(LANGUAGE_STORAGE_KEY, language);
-
-  // Handle RTL layout direction
-  const isRTL = LANGUAGES[language].rtl;
-  if (I18nManager.isRTL !== isRTL) {
-    I18nManager.allowRTL(isRTL);
-    I18nManager.forceRTL(isRTL);
-    // Note: App restart is required for RTL changes to take full effect
-  }
-}
-
-/**
- * Check if the current language is RTL
- */
-export function isCurrentLanguageRTL(): boolean {
-  const currentLang = getCurrentLanguage();
-  return LANGUAGES[currentLang]?.rtl ?? false;
-}
-
-/**
- * Get all available languages as an array for UI selectors
- */
-export function getAvailableLanguages(): Array<{
-  code: LanguageCode;
-  name: string;
-  nativeName: string;
-  rtl: boolean;
-}> {
-  return Object.entries(LANGUAGES).map(([code, config]) => ({
-    code: code as LanguageCode,
-    ...config,
-  }));
-}
-
-/**
- * Get current language
- */
-export function getCurrentLanguage(): LanguageCode {
-  return (i18n.language || "en") as LanguageCode;
-}
-
-/**
- * Hook-friendly RTL detection
- * Returns current RTL state from I18nManager
- */
-export function isRTL(): boolean {
-  return I18nManager.isRTL;
-}
-
-/**
- * Get text alignment based on RTL
- * Useful for styling text components
- */
-export function getTextAlign(): "left" | "right" {
-  return I18nManager.isRTL ? "right" : "left";
-}
-
-/**
- * Get flex direction based on RTL
- * Useful for horizontal layouts
- */
-export function getFlexDirection(): "row" | "row-reverse" {
-  return I18nManager.isRTL ? "row-reverse" : "row";
-}
-
-/**
- * Get start/end values swapped for RTL
- * Useful for margins, paddings, and positioning
- */
-export function getStartEnd(): { start: "left" | "right"; end: "left" | "right" } {
-  return I18nManager.isRTL
-    ? { start: "right", end: "left" }
-    : { start: "left", end: "right" };
-}
-
-/**
- * Transform a value for RTL (e.g., for translateX animations)
- * @param value - The original value
- * @returns The transformed value (negated for RTL)
- */
-export function rtlTransform(value: number): number {
-  return I18nManager.isRTL ? -value : value;
-}
-
-/**
- * Check if a specific language requires RTL
- */
-export function isLanguageRTL(languageCode: string): boolean {
-  const lang = LANGUAGES[languageCode as LanguageCode];
-  return lang?.rtl ?? false;
-}
-
-/**
- * Force app restart for RTL changes to take effect
- * Call this after changing to/from an RTL language
- */
-export async function applyRTLAndRestart(isRTL: boolean): Promise<void> {
-  I18nManager.allowRTL(isRTL);
-  I18nManager.forceRTL(isRTL);
-  // Note: In production, use expo-updates to reload the app
-  // await Updates.reloadAsync();
-}
-
-export { i18n };
-export default i18n;
+/**
+ * @fileoverview Internationalization (i18n) setup with RTL support
+ * Provides multi-language support with automatic device language detection.
+ * @module i18n
+ */
+
+import i18n from "i18next";
+import { initReactI18next } from "react-i18next";
+import * as Localization from "expo-localization";
+import { I18nManager } from "react-native";
+import { storage } from "@/services/storage";
+
+import en from "./locales/en.json";
+import fr from "./locales/fr.json";
+import es from "./locales/es.json";
+import de from "./locales/de.json";
+import ar from "./locales/ar.json";
+
+/**
+ * Supported languages configuration.
+ * Each language includes its English name, native name, and RTL flag.
+ */
+export const LANGUAGES = {
+  en: { name: "English", nativeName: "English", rtl: false },
+  fr: { name: "French", nativeName: "Français", rtl: false },
+  es: { name: "Spanish", nativeName: "Español", rtl: false },
+  de: { name: "German", nativeName: "Deutsch", rtl: false },
+  ar: { name: "Arabic", nativeName: "العربية", rtl: true },
+} as const;
+
+export type LanguageCode = keyof typeof LANGUAGES;
+
+const LANGUAGE_STORAGE_KEY = "app_language";
+
+const resources = {
+  en: { translation: en },
+  fr: { translation: fr },
+  es: { translation: es },
+  de: { translation: de },
+  ar: { translation: ar },
+};
+
+/**
+ * Get the device's preferred language
+ * Falls back to 'en' if not supported
+ */
+function getDeviceLanguage(): LanguageCode {
+  const locale = Localization.getLocales()[0];
+  const languageCode = locale?.languageCode || "en";
+
+  // Check if we support this language
+  if (languageCode in LANGUAGES) {
+    return languageCode as LanguageCode;
+  }
+
+  return "en";
+}
+
+/**
+ * Initialize i18n with the saved language or device language
+ */
+export async function initI18n(): Promise<void> {
+  // Try to get saved language preference
+  const savedLanguage = await storage.get<LanguageCode>(LANGUAGE_STORAGE_KEY);
+  const initialLanguage = savedLanguage || getDeviceLanguage();
+
+  await i18n.use(initReactI18next).init({
+    resources,
+    lng: initialLanguage,
+    fallbackLng: "en",
+    compatibilityJSON: "v3",
+    interpolation: {
+      escapeValue: false, // React already escapes values
+    },
+    react: {
+      useSuspense: false, // Prevents issues with SSR/async loading
+    },
+  });
+}
+
+/**
+ * Change the app language and apply RTL settings if needed.
+ * Note: RTL changes require an app restart to take full effect.
+ *
+ * @param language - The language code to switch to
+ * @returns Promise that resolves when the language is changed
+ */
+export async function changeLanguage(language: LanguageCode): Promise<void> {
+  await i18n.changeLanguage(language);
+  await storage.set(LANGUAGE_STORAGE_KEY, language);
+
+  // Handle RTL layout direction
+  const isRTL = LANGUAGES[language].rtl;
+  if (I18nManager.isRTL !== isRTL) {
+    I18nManager.allowRTL(isRTL);
+    I18nManager.forceRTL(isRTL);
+    // Note: App restart is required for RTL changes to take full effect
+  }
+}
+
+/**
+ * Check if the current language is RTL
+ */
+export function isCurrentLanguageRTL(): boolean {
+  const currentLang = getCurrentLanguage();
+  return LANGUAGES[currentLang]?.rtl ?? false;
+}
+
+/**
+ * Get all available languages as an array for UI selectors
+ */
+export function getAvailableLanguages(): {
+  code: LanguageCode;
+  name: string;
+  nativeName: string;
+  rtl: boolean;
+}[] {
+  return Object.entries(LANGUAGES).map(([code, config]) => ({
+    code: code as LanguageCode,
+    ...config,
+  }));
+}
+
+/**
+ * Get current language
+ */
+export function getCurrentLanguage(): LanguageCode {
+  return (i18n.language || "en") as LanguageCode;
+}
+
+/**
+ * Hook-friendly RTL detection
+ * Returns current RTL state from I18nManager
+ */
+export function isRTL(): boolean {
+  return I18nManager.isRTL;
+}
+
+/**
+ * Get text alignment based on RTL
+ * Useful for styling text components
+ */
+export function getTextAlign(): "left" | "right" {
+  return I18nManager.isRTL ? "right" : "left";
+}
+
+/**
+ * Get flex direction based on RTL
+ * Useful for horizontal layouts
+ */
+export function getFlexDirection(): "row" | "row-reverse" {
+  return I18nManager.isRTL ? "row-reverse" : "row";
+}
+
+/**
+ * Get start/end values swapped for RTL
+ * Useful for margins, paddings, and positioning
+ */
+export function getStartEnd(): {
+  start: "left" | "right";
+  end: "left" | "right";
+} {
+  return I18nManager.isRTL
+    ? { start: "right", end: "left" }
+    : { start: "left", end: "right" };
+}
+
+/**
+ * Transform a value for RTL (e.g., for translateX animations)
+ * @param value - The original value
+ * @returns The transformed value (negated for RTL)
+ */
+export function rtlTransform(value: number): number {
+  return I18nManager.isRTL ? -value : value;
+}
+
+/**
+ * Check if a specific language requires RTL
+ */
+export function isLanguageRTL(languageCode: string): boolean {
+  const lang = LANGUAGES[languageCode as LanguageCode];
+  return lang?.rtl ?? false;
+}
+
+/**
+ * Force app restart for RTL changes to take effect
+ * Call this after changing to/from an RTL language
+ */
+export async function applyRTLAndRestart(isRTL: boolean): Promise<void> {
+  I18nManager.allowRTL(isRTL);
+  I18nManager.forceRTL(isRTL);
+  // Note: In production, use expo-updates to reload the app
+  // await Updates.reloadAsync();
+}
+
+export { i18n };
+export default i18n;