@umituz/react-native-design-system 2.9.27 → 2.9.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-design-system",
-  "version": "2.9.27",
+  "version": "2.9.28",
   "description": "Universal design system for React Native apps - Consolidated package with atoms, molecules, organisms, theme, typography, responsive, safe area, exception, infinite scroll, UUID, image, timezone, offline, onboarding, and loading utilities",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/exports/init.ts

@@ -0,0 +1,5 @@
+/**
+ * Init Module Exports
+ */
+
+export * from "../init";

package/src/index.ts

@@ -130,3 +130,8 @@ export * from './exports/tanstack';
 // LOADING EXPORTS
 // =============================================================================
 export * from './exports/loading';
+
+// =============================================================================
+// INIT EXPORTS
+// =============================================================================
+export * from './exports/init';

package/src/init/createAppInitializer.ts

@@ -0,0 +1,162 @@
+/**
+ * App Initializer Factory
+ * Creates a singleton app initializer with ordered module execution
+ */
+
+import type {
+  AppInitializerConfig,
+  AppInitializerResult,
+  InitModule,
+} from "./types";
+
+declare const __DEV__: boolean;
+
+/**
+ * Create an app initializer with singleton pattern
+ *
+ * @example
+ * ```typescript
+ * const initializeApp = createAppInitializer({
+ *   modules: [
+ *     { name: 'firebase', init: initFirebase, critical: true },
+ *     { name: 'auth', init: initAuth, critical: true, dependsOn: ['firebase'] },
+ *     { name: 'subscription', init: initSubscription, dependsOn: ['auth'] },
+ *     { name: 'ai', init: initAI },
+ *   ],
+ * });
+ *
+ * await initializeApp();
+ * ```
+ */
+export function createAppInitializer(
+  config: AppInitializerConfig
+): () => Promise<AppInitializerResult> {
+  const {
+    modules,
+    debug = typeof __DEV__ !== "undefined" && __DEV__,
+    continueOnError = true,
+    onComplete,
+    onError,
+  } = config;
+
+  let initializationPromise: Promise<AppInitializerResult> | null = null;
+  let isInitialized = false;
+
+  const log = (message: string, ...args: unknown[]) => {
+    if (debug) {
+      console.log(`[AppInit] ${message}`, ...args);
+    }
+  };
+
+  const sortModulesByDependency = (mods: InitModule[]): InitModule[] => {
+    const sorted: InitModule[] = [];
+    const visited = new Set<string>();
+    const visiting = new Set<string>();
+
+    const visit = (mod: InitModule) => {
+      if (visited.has(mod.name)) return;
+      if (visiting.has(mod.name)) {
+        throw new Error(`Circular dependency detected: ${mod.name}`);
+      }
+
+      visiting.add(mod.name);
+
+      if (mod.dependsOn) {
+        for (const depName of mod.dependsOn) {
+          const dep = mods.find((m) => m.name === depName);
+          if (dep) visit(dep);
+        }
+      }
+
+      visiting.delete(mod.name);
+      visited.add(mod.name);
+      sorted.push(mod);
+    };
+
+    for (const mod of mods) {
+      visit(mod);
+    }
+
+    return sorted;
+  };
+
+  const performInitialization = async (): Promise<AppInitializerResult> => {
+    const startTime = Date.now();
+    const failedModules: string[] = [];
+
+    log("Starting initialization...");
+
+    const sortedModules = sortModulesByDependency(modules);
+
+    for (const mod of sortedModules) {
+      log(`Initializing: ${mod.name}`);
+
+      try {
+        const result = await mod.init();
+
+        if (result === false) {
+          throw new Error(`Module ${mod.name} returned false`);
+        }
+
+        log(`Completed: ${mod.name}`);
+      } catch (error) {
+        log(`Failed: ${mod.name}`, error);
+        failedModules.push(mod.name);
+
+        onError?.(mod.name, error);
+
+        if (mod.critical && !continueOnError) {
+          return {
+            success: false,
+            failedModules,
+            duration: Date.now() - startTime,
+          };
+        }
+      }
+    }
+
+    const duration = Date.now() - startTime;
+    const success = failedModules.length === 0;
+
+    log(`Initialization complete in ${duration}ms`, {
+      success,
+      failedModules,
+    });
+
+    isInitialized = true;
+    onComplete?.();
+
+    return { success, failedModules, duration };
+  };
+
+  return async () => {
+    if (isInitialized) {
+      return { success: true, failedModules: [], duration: 0 };
+    }
+
+    if (initializationPromise) {
+      return initializationPromise;
+    }
+
+    initializationPromise = performInitialization();
+    return initializationPromise;
+  };
+}
+
+/**
+ * Create a simple initialization module
+ */
+export function createInitModule(
+  name: string,
+  init: () => Promise<void> | void,
+  options?: Partial<Omit<InitModule, "name" | "init">>
+): InitModule {
+  return {
+    name,
+    init: async () => {
+      await init();
+      return true;
+    },
+    ...options,
+  };
+}

package/src/init/env/createEnvConfig.ts

@@ -0,0 +1,170 @@
+/**
+ * Environment Configuration Factory
+ * Creates type-safe environment accessors
+ */
+
+import { Platform } from "react-native";
+import type {
+  EnvConfig,
+  EnvAccessor,
+  EnvSourceConfig,
+  FirebaseEnvConfig,
+} from "./types";
+
+declare const __DEV__: boolean;
+
+/**
+ * Default key mappings for environment variables
+ */
+const DEFAULT_KEY_MAPPINGS: Record<string, string> = {
+  // RevenueCat
+  EXPO_PUBLIC_REVENUECAT_PROD_API_KEY_IOS: "revenueCatApiKeyIos",
+  EXPO_PUBLIC_REVENUECAT_PROD_API_KEY_ANDROID: "revenueCatApiKeyAndroid",
+  EXPO_PUBLIC_REVENUECAT_IOS_KEY: "revenueCatApiKeyIos",
+  EXPO_PUBLIC_REVENUECAT_ANDROID_KEY: "revenueCatApiKeyAndroid",
+  // FAL AI
+  EXPO_PUBLIC_FAL_AI_API_KEY: "falApiKey",
+  EXPO_PUBLIC_FAL_AI_BASE_URL: "falBaseUrl",
+  // Firebase
+  EXPO_PUBLIC_FIREBASE_API_KEY: "firebaseApiKey",
+  EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN: "firebaseAuthDomain",
+  EXPO_PUBLIC_FIREBASE_PROJECT_ID: "firebaseProjectId",
+  EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET: "firebaseStorageBucket",
+  EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID: "firebaseMessagingSenderId",
+  EXPO_PUBLIC_FIREBASE_APP_ID: "firebaseAppId",
+  // OpenAI
+  EXPO_PUBLIC_OPENAI_API_KEY: "openAIApiKey",
+};
+
+/**
+ * Get environment value with fallback chain
+ */
+function getEnvValue(
+  key: string,
+  sources: EnvSourceConfig,
+  keyMappings: Record<string, string>
+): string | undefined {
+  // 1. Try process.env first
+  if (sources.processEnv?.[key]) {
+    return sources.processEnv[key];
+  }
+
+  // 2. Try mapped extra key
+  const mappedKey = keyMappings[key];
+  if (mappedKey && sources.expoExtra) {
+    const value = sources.expoExtra[mappedKey];
+    // Filter out placeholder strings
+    if (typeof value === "string" && !value.startsWith("$EXPO_PUBLIC_")) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Create environment configuration accessor
+ *
+ * @example
+ * ```typescript
+ * import Constants from 'expo-constants';
+ *
+ * const env = createEnvConfig({
+ *   revenueCat: {
+ *     testStoreKey: 'test_xxx', // Only used in __DEV__
+ *   },
+ *   fal: {
+ *     baseUrl: 'https://fal.run',
+ *   },
+ * }, {
+ *   expoExtra: Constants.expoConfig?.extra,
+ *   processEnv: process.env,
+ * });
+ *
+ * const apiKey = env.getRevenueCatApiKey();
+ * ```
+ */
+export function createEnvConfig(
+  config: EnvConfig = {},
+  sources: EnvSourceConfig = {}
+): EnvAccessor {
+  // Default sources
+  const resolvedSources: EnvSourceConfig = {
+    expoExtra: sources.expoExtra ?? {},
+    processEnv: sources.processEnv ?? (process.env as Record<string, string>),
+  };
+
+  const get = (key: string): string | undefined => {
+    // Check custom config first
+    if (config.custom?.[key]) {
+      return config.custom[key];
+    }
+    return getEnvValue(key, resolvedSources, DEFAULT_KEY_MAPPINGS);
+  };
+
+  const getRevenueCatApiKey = (): string => {
+    const platformKey =
+      Platform.OS === "ios"
+        ? config.revenueCat?.iosKey ||
+          get("EXPO_PUBLIC_REVENUECAT_PROD_API_KEY_IOS") ||
+          get("EXPO_PUBLIC_REVENUECAT_IOS_KEY")
+        : config.revenueCat?.androidKey ||
+          get("EXPO_PUBLIC_REVENUECAT_PROD_API_KEY_ANDROID") ||
+          get("EXPO_PUBLIC_REVENUECAT_ANDROID_KEY");
+
+    return platformKey || "";
+  };
+
+  const getRevenueCatTestStoreKey = (): string | undefined => {
+    // Only return test store key in development
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      return config.revenueCat?.testStoreKey;
+    }
+    return undefined;
+  };
+
+  const getFalApiKey = (): string => {
+    return (
+      config.fal?.apiKey || get("EXPO_PUBLIC_FAL_AI_API_KEY") || ""
+    );
+  };
+
+  const getFalBaseUrl = (): string => {
+    return (
+      config.fal?.baseUrl ||
+      get("EXPO_PUBLIC_FAL_AI_BASE_URL") ||
+      "https://fal.run"
+    );
+  };
+
+  const getFirebaseConfig = (): FirebaseEnvConfig => ({
+    apiKey:
+      config.firebase?.apiKey || get("EXPO_PUBLIC_FIREBASE_API_KEY") || "",
+    authDomain:
+      config.firebase?.authDomain ||
+      get("EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN") ||
+      "",
+    projectId:
+      config.firebase?.projectId ||
+      get("EXPO_PUBLIC_FIREBASE_PROJECT_ID") ||
+      "",
+    storageBucket:
+      config.firebase?.storageBucket ||
+      get("EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET") ||
+      "",
+    messagingSenderId:
+      config.firebase?.messagingSenderId ||
+      get("EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID") ||
+      "",
+    appId: config.firebase?.appId || get("EXPO_PUBLIC_FIREBASE_APP_ID") || "",
+  });
+
+  return {
+    getRevenueCatApiKey,
+    getRevenueCatTestStoreKey,
+    getFalApiKey,
+    getFalBaseUrl,
+    getFirebaseConfig,
+    get,
+  };
+}

package/src/init/env/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Environment Configuration
+ */
+
+export { createEnvConfig } from "./createEnvConfig";
+export type {
+  EnvConfig,
+  EnvAccessor,
+  EnvSourceConfig,
+  RevenueCatEnvConfig,
+  FalEnvConfig,
+  FirebaseEnvConfig,
+} from "./types";

package/src/init/env/types.ts

@@ -0,0 +1,86 @@
+/**
+ * Environment Configuration Types
+ */
+
+/**
+ * Environment source configuration
+ */
+export interface EnvSourceConfig {
+  /** Expo Constants extra config */
+  expoExtra?: Record<string, unknown>;
+  /** Process env (for EXPO_PUBLIC_ vars) */
+  processEnv?: Record<string, string | undefined>;
+}
+
+/**
+ * Key mapping from EXPO_PUBLIC_ to extra key
+ */
+export interface EnvKeyMapping {
+  /** Environment variable name (e.g., 'EXPO_PUBLIC_FAL_API_KEY') */
+  envKey: string;
+  /** Extra config key (e.g., 'falApiKey') */
+  extraKey: string;
+}
+
+/**
+ * RevenueCat configuration
+ */
+export interface RevenueCatEnvConfig {
+  /** iOS API key */
+  iosKey?: string;
+  /** Android API key */
+  androidKey?: string;
+  /** Test store key (for development) */
+  testStoreKey?: string;
+}
+
+/**
+ * FAL AI configuration
+ */
+export interface FalEnvConfig {
+  /** API key */
+  apiKey?: string;
+  /** Base URL (default: https://fal.run) */
+  baseUrl?: string;
+}
+
+/**
+ * Firebase configuration
+ */
+export interface FirebaseEnvConfig {
+  apiKey?: string;
+  authDomain?: string;
+  projectId?: string;
+  storageBucket?: string;
+  messagingSenderId?: string;
+  appId?: string;
+}
+
+/**
+ * Full environment configuration
+ */
+export interface EnvConfig {
+  revenueCat?: RevenueCatEnvConfig;
+  fal?: FalEnvConfig;
+  firebase?: FirebaseEnvConfig;
+  /** Custom keys */
+  custom?: Record<string, string | undefined>;
+}
+
+/**
+ * Created environment accessor
+ */
+export interface EnvAccessor {
+  /** Get RevenueCat API key (platform-specific) */
+  getRevenueCatApiKey: () => string;
+  /** Get RevenueCat test store key (dev only) */
+  getRevenueCatTestStoreKey: () => string | undefined;
+  /** Get FAL API key */
+  getFalApiKey: () => string;
+  /** Get FAL base URL */
+  getFalBaseUrl: () => string;
+  /** Get Firebase config */
+  getFirebaseConfig: () => FirebaseEnvConfig;
+  /** Get custom env value */
+  get: (key: string) => string | undefined;
+}

package/src/init/index.ts

@@ -0,0 +1,29 @@
+/**
+ * App Initialization Module
+ *
+ * Provides utilities for app initialization:
+ * - createAppInitializer: Factory for creating app initializers
+ * - useAppInitialization: Hook for managing initialization state
+ * - createEnvConfig: Environment configuration factory
+ */
+
+// App Initializer
+export {
+  createAppInitializer,
+  createInitModule,
+} from "./createAppInitializer";
+
+// Initialization Hook
+export { useAppInitialization } from "./useAppInitialization";
+
+// Environment Configuration
+export * from "./env";
+
+// Types
+export type {
+  InitModule,
+  AppInitializerConfig,
+  AppInitializerResult,
+  UseAppInitializationOptions,
+  UseAppInitializationReturn,
+} from "./types";

package/src/init/types.ts

@@ -0,0 +1,63 @@
+/**
+ * App Initialization Types
+ */
+
+/**
+ * Single initialization module
+ */
+export interface InitModule {
+  /** Module name for logging */
+  name: string;
+  /** Initialize function - returns success status */
+  init: () => Promise<boolean> | boolean;
+  /** Optional: Whether this module is critical (default: false) */
+  critical?: boolean;
+  /** Optional: Dependencies - other module names that must run first */
+  dependsOn?: string[];
+}
+
+/**
+ * App initializer configuration
+ */
+export interface AppInitializerConfig {
+  /** Initialization modules to run */
+  modules: InitModule[];
+  /** Enable debug logging (default: __DEV__) */
+  debug?: boolean;
+  /** Continue on non-critical module failure (default: true) */
+  continueOnError?: boolean;
+  /** Callback when all modules complete */
+  onComplete?: () => void;
+  /** Callback on error */
+  onError?: (moduleName: string, error: unknown) => void;
+}
+
+/**
+ * App initializer result
+ */
+export interface AppInitializerResult {
+  success: boolean;
+  failedModules: string[];
+  duration: number;
+}
+
+/**
+ * useAppInitialization hook options
+ */
+export interface UseAppInitializationOptions {
+  /** Skip initialization (useful for testing) */
+  skip?: boolean;
+  /** Callback when initialization completes */
+  onReady?: () => void;
+  /** Callback on error */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * useAppInitialization hook return type
+ */
+export interface UseAppInitializationReturn {
+  isReady: boolean;
+  isLoading: boolean;
+  error: Error | null;
+}

package/src/init/useAppInitialization.ts

@@ -0,0 +1,75 @@
+/**
+ * useAppInitialization Hook
+ * Manages app initialization state in React components
+ */
+
+import { useState, useEffect, useCallback } from "react";
+import type {
+  UseAppInitializationOptions,
+  UseAppInitializationReturn,
+  AppInitializerResult,
+} from "./types";
+
+/**
+ * Hook to manage app initialization
+ *
+ * @example
+ * ```typescript
+ * const { isReady, isLoading, error } = useAppInitialization(initializeApp, {
+ *   onReady: () => console.log('App ready!'),
+ * });
+ *
+ * if (isLoading) return <SplashScreen />;
+ * if (error) return <ErrorScreen error={error} />;
+ * return <App />;
+ * ```
+ */
+export function useAppInitialization(
+  initializer: () => Promise<AppInitializerResult>,
+  options: UseAppInitializationOptions = {}
+): UseAppInitializationReturn {
+  const { skip = false, onReady, onError } = options;
+
+  const [isReady, setIsReady] = useState(false);
+  const [isLoading, setIsLoading] = useState(!skip);
+  const [error, setError] = useState<Error | null>(null);
+
+  const initialize = useCallback(async () => {
+    if (skip) {
+      setIsReady(true);
+      setIsLoading(false);
+      return;
+    }
+
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      const result = await initializer();
+
+      if (!result.success && result.failedModules.length > 0) {
+        const criticalFailed = result.failedModules.length > 0;
+        if (criticalFailed) {
+          throw new Error(
+            `Initialization failed: ${result.failedModules.join(", ")}`
+          );
+        }
+      }
+
+      setIsReady(true);
+      onReady?.();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      setError(error);
+      onError?.(error);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [initializer, skip, onReady, onError]);
+
+  useEffect(() => {
+    initialize();
+  }, [initialize]);
+
+  return { isReady, isLoading, error };
+}