@umituz/react-native-design-system 4.27.35 → 4.28.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@umituz/react-native-design-system",
-  "version": "4.27.35",
-  "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 - TanStack persistence and expo-image-manipulator now lazy loaded",
+  "version": "4.28.0",
+  "description": "Universal design system for React Native apps with safe navigation hooks that work outside NavigationContainer",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
   "sideEffects": false,

package/src/molecules/navigation/hooks/useAppFocusEffect.ts

@@ -1,19 +1,42 @@
-import { useFocusEffect } from "@react-navigation/native";
+import { useFocusEffect as useRNFocusEffect } from "@react-navigation/native";
+import { useEffect } from "react";
 
 /**
  * useAppFocusEffect Hook
  *
- * Wrapper around React Navigation's useFocusEffect.
- * Pass a useCallback-wrapped effect to avoid re-running on every render.
+ * Safe wrapper around React Navigation's useFocusEffect.
+ * Only runs the effect if navigation is ready.
  *
- * Usage:
- *   useAppFocusEffect(
- *     useCallback(() => {
- *       doSomething();
- *       return () => cleanup();
- *     }, [deps])
- *   );
+ * @param effect - Callback to run when screen is focused
+ *
+ * @example
+ * ```typescript
+ * useAppFocusEffect(
+ *   useCallback(() => {
+ *     // Runs when screen is focused
+ *     return () => {
+ *       // Cleanup when screen is unfocused
+ *     };
+ *   }, [dependency])
+ * );
+ * ```
  */
 export function useAppFocusEffect(effect: () => void | (() => void)): void {
-  useFocusEffect(effect);
+  try {
+    // Try to use React Navigation's useFocusEffect
+    useRNFocusEffect(effect);
+  } catch (error) {
+    // Navigation not ready - run effect once and cleanup
+    if (__DEV__) {
+      console.warn('[useAppFocusEffect] Navigation not ready. Running effect once instead.');
+    }
+    useEffect(() => {
+      const cleanup = effect();
+      return () => {
+        if (typeof cleanup === 'function') {
+          cleanup();
+        }
+      };
+    }, [effect]);
+  }
 }

package/src/molecules/navigation/hooks/useAppIsFocused.ts

@@ -1,11 +1,28 @@
-import { useIsFocused } from "@react-navigation/native";
+import { useIsFocused as useRNIsFocused } from "@react-navigation/native";
+import { useMemo } from "react";
 
 /**
  * useAppIsFocused Hook
  *
- * A wrapper around React Navigation's useIsFocused hook.
- * Standardizes API usage across all packages and apps.
+ * Safe wrapper around React Navigation's useIsFocused.
+ * Returns false if called outside NavigationContainer.
+ *
+ * @example
+ * ```typescript
+ * const isFocused = useAppIsFocused();
+ * if (isFocused) {
+ *   // Screen is currently focused
+ * }
+ * ```
  */
 export function useAppIsFocused(): boolean {
-  return useIsFocused();
+  try {
+    return useRNIsFocused();
+  } catch (error) {
+    // Navigation not ready - return false
+    if (__DEV__) {
+      console.warn('[useAppIsFocused] Navigation not ready. Returning false.');
+    }
+    return false;
+  }
 }

package/src/molecules/navigation/hooks/useAppNavigation.ts

@@ -16,6 +16,55 @@ export interface AppNavigationResult {
   canGoBack: () => boolean;
   getState: () => ReturnType<NavigationProp<ParamListBase>["getState"]>;
   getParent: () => NavigationProp<ParamListBase> | undefined;
+  /** Whether navigation is available (inside NavigationContainer) */
+  isReady: boolean;
+}
+
+/**
+ * Creates a no-op navigation object for use outside NavigationContainer
+ */
+function createNoOpNavigation(): AppNavigationResult {
+  return {
+    navigate: () => {
+      if (__DEV__) {
+        console.warn('[useAppNavigation] Navigation not ready. Component must be inside NavigationContainer.');
+      }
+    },
+    push: () => {
+      if (__DEV__) {
+        console.warn('[useAppNavigation] Navigation not ready. Component must be inside NavigationContainer.');
+      }
+    },
+    goBack: () => {
+      if (__DEV__) {
+        console.warn('[useAppNavigation] Navigation not ready. Component must be inside NavigationContainer.');
+      }
+    },
+    reset: () => {
+      if (__DEV__) {
+        console.warn('[useAppNavigation] Navigation not ready. Component must be inside NavigationContainer.');
+      }
+    },
+    replace: () => {
+      if (__DEV__) {
+        console.warn('[useAppNavigation] Navigation not ready. Component must be inside NavigationContainer.');
+      }
+    },
+    pop: () => {
+      if (__DEV__) {
+        console.warn('[useAppNavigation] Navigation not ready. Component must be inside NavigationContainer.');
+      }
+    },
+    popToTop: () => {
+      if (__DEV__) {
+        console.warn('[useAppNavigation] Navigation not ready. Component must be inside NavigationContainer.');
+      }
+    },
+    canGoBack: () => false,
+    getState: () => ({ key: 'root', index: 0, routeNames: [], history: [], routes: [], type: 'nav', stale: false }),
+    getParent: () => undefined,
+    isReady: false,
+  };
 }
 
 /**
@@ -23,82 +72,93 @@ export interface AppNavigationResult {
  *
  * Clean navigation API without complex type casting.
  * Uses navigation.navigate() directly for proper nested navigator support.
+ *
+ * Safe to use outside NavigationContainer - returns no-op functions.
+ *
  * Use: const navigation = useAppNavigation();
- *      navigation.navigate("ScreenName", { param: value });
+ *      if (navigation.isReady) {
+ *        navigation.navigate("ScreenName", { param: value });
+ *      }
  */
 export function useAppNavigation(): AppNavigationResult {
-  const navigation = useNavigation<NavigationProp<ParamListBase>>();
+  try {
+    const navigation = useNavigation<NavigationProp<ParamListBase>>();
 
-  const navigate = useCallback(
-    (screen: string, params?: Record<string, unknown>) => {
-      // Dynamic navigation: use CommonActions for type-safe arbitrary screen navigation
-      navigation.dispatch(
-        CommonActions.navigate({
-          name: screen,
-          params,
-        })
-      );
-    },
-    [navigation]
-  );
+    const navigate = useCallback(
+      (screen: string, params?: Record<string, unknown>) => {
+        // Dynamic navigation: use CommonActions for type-safe arbitrary screen navigation
+        navigation.dispatch(
+          CommonActions.navigate({
+            name: screen,
+            params,
+          })
+        );
+      },
+      [navigation]
+    );
 
-  const push = useCallback(
-    (screen: string, params?: Record<string, unknown>) => {
-      navigation.dispatch(StackActions.push(screen, params));
-    },
-    [navigation]
-  );
+    const push = useCallback(
+      (screen: string, params?: Record<string, unknown>) => {
+        navigation.dispatch(StackActions.push(screen, params));
+      },
+      [navigation]
+    );
 
-  const goBack = useCallback(() => {
-    if (navigation.canGoBack()) {
-      navigation.goBack();
-    }
-  }, [navigation]);
+    const goBack = useCallback(() => {
+      if (navigation.canGoBack()) {
+        navigation.goBack();
+      }
+    }, [navigation]);
 
-  const reset = useCallback(
-    (screen: string, params?: Record<string, unknown>) => {
-      navigation.reset({ index: 0, routes: [{ name: screen, params }] });
-    },
-    [navigation]
-  );
+    const reset = useCallback(
+      (screen: string, params?: Record<string, unknown>) => {
+        navigation.reset({ index: 0, routes: [{ name: screen, params }] });
+      },
+      [navigation]
+    );
 
-  const replace = useCallback(
-    (screen: string, params?: Record<string, unknown>) => {
-      navigation.dispatch(StackActions.replace(screen, params));
-    },
-    [navigation]
-  );
+    const replace = useCallback(
+      (screen: string, params?: Record<string, unknown>) => {
+        navigation.dispatch(StackActions.replace(screen, params));
+      },
+      [navigation]
+    );
 
-  const pop = useCallback(
-    (count = 1) => {
-      navigation.dispatch(StackActions.pop(count));
-    },
-    [navigation]
-  );
+    const pop = useCallback(
+      (count = 1) => {
+        navigation.dispatch(StackActions.pop(count));
+      },
+      [navigation]
+    );
 
-  const popToTop = useCallback(() => {
-    navigation.dispatch(StackActions.popToTop());
-  }, [navigation]);
+    const popToTop = useCallback(() => {
+      navigation.dispatch(StackActions.popToTop());
+    }, [navigation]);
 
-  const canGoBack = useCallback(() => navigation.canGoBack(), [navigation]);
+    const canGoBack = useCallback(() => navigation.canGoBack(), [navigation]);
 
-  const getState = useCallback(() => navigation.getState(), [navigation]);
+    const getState = useCallback(() => navigation.getState(), [navigation]);
 
-  const getParent = useCallback(() => navigation.getParent(), [navigation]);
+    const getParent = useCallback(() => navigation.getParent(), [navigation]);
 
-  return useMemo(
-    () => ({
-      navigate,
-      push,
-      goBack,
-      reset,
-      replace,
-      pop,
-      popToTop,
-      canGoBack,
-      getState,
-      getParent,
-    }),
-    [navigate, push, goBack, reset, replace, pop, popToTop, canGoBack, getState, getParent]
-  );
+    return useMemo(
+      () => ({
+        navigate,
+        push,
+        goBack,
+        reset,
+        replace,
+        pop,
+        popToTop,
+        canGoBack,
+        getState,
+        getParent,
+        isReady: true,
+      }),
+      [navigate, push, goBack, reset, replace, pop, popToTop, canGoBack, getState, getParent]
+    );
+  } catch (error) {
+    // Navigation not ready - return no-op navigation
+    return createNoOpNavigation();
+  }
 }

package/src/molecules/navigation/hooks/useAppRoute.ts

@@ -1,14 +1,50 @@
 import { useRoute } from "@react-navigation/native";
 import type { RouteProp, ParamListBase } from "@react-navigation/native";
+import { useMemo } from "react";
 
 /**
  * useAppRoute Hook
  *
- * A wrapper around React Navigation's useRoute hook.
- * Standardizes route usage across all packages and apps.
+ * Safe wrapper around React Navigation's useRoute hook.
+ * Returns empty route params if called outside NavigationContainer.
+ *
+ * @example
+ * ```typescript
+ * const route = useAppRoute();
+ * if (route.isReady) {
+ *   const params = route.params;
+ * }
+ * ```
  */
-export function useAppRoute<T extends ParamListBase, RouteName extends keyof T = string>(): RouteProp<T, RouteName> {
-  return useRoute<RouteProp<T, RouteName>>();
+export function useAppRoute<
+  T extends ParamListBase = ParamListBase,
+  RouteName extends keyof T = keyof T
+>(): RouteProp<T, RouteName> & { isReady: boolean } {
+  try {
+    const route = useRoute<RouteProp<T, RouteName>>();
+    return useMemo(
+      () => ({
+        ...route,
+        isReady: true,
+      }),
+      [route]
+    );
+  } catch (error) {
+    // Route not ready - return empty route
+    if (__DEV__) {
+      console.warn('[useAppRoute] Route not ready. Component must be inside NavigationContainer.');
+    }
+    return useMemo(
+      () => ({
+        key: '',
+        name: '' as RouteName,
+        params: undefined,
+        path: undefined,
+        isReady: false,
+      } as RouteProp<T, RouteName> & { isReady: boolean }),
+      []
+    );
+  }
 }
 
 export type { RouteProp };