@croacroa/react-native-template 1.0.0 → 2.0.0

package/hooks/useTheme.tsx

@@ -1,3 +1,9 @@
+/**
+ * @fileoverview Theme management with light/dark mode support
+ * Provides context and hooks for managing app theme with system preference detection.
+ * @module hooks/useTheme
+ */
+
 import {
   createContext,
   useContext,
@@ -8,13 +14,27 @@ import {
 import { useColorScheme } from "react-native";
 import AsyncStorage from "@react-native-async-storage/async-storage";
 
+/**
+ * Theme mode options
+ * - 'light': Force light theme
+ * - 'dark': Force dark theme
+ * - 'system': Follow device system preference
+ */
 type ThemeMode = "light" | "dark" | "system";
 
+/**
+ * Theme context type definition
+ */
 interface ThemeContextType {
+  /** Current theme mode setting ('light', 'dark', or 'system') */
   mode: ThemeMode;
+  /** Whether the current effective theme is dark */
   isDark: boolean;
+  /** Whether the theme has been loaded from storage */
   isLoaded: boolean;
+  /** Set the theme mode and persist to storage */
   setMode: (mode: ThemeMode) => void;
+  /** Toggle between light and dark mode */
   toggleTheme: () => void;
 }
 
@@ -22,6 +42,29 @@ const ThemeContext = createContext<ThemeContextType | undefined>(undefined);
 
 const THEME_KEY = "theme_mode";
 
+/**
+ * Theme Provider component.
+ * Wraps your app to provide theme context with persistent preferences.
+ *
+ * Features:
+ * - System theme detection
+ * - Persistent theme preference
+ * - Real-time system theme updates
+ *
+ * @param children - Child components to wrap
+ *
+ * @example
+ * ```tsx
+ * // In your app root
+ * export default function RootLayout() {
+ *   return (
+ *     <ThemeProvider>
+ *       <App />
+ *     </ThemeProvider>
+ *   );
+ * }
+ * ```
+ */
 export function ThemeProvider({ children }: { children: ReactNode }) {
   const systemColorScheme = useColorScheme();
   const [mode, setModeState] = useState<ThemeMode>("system");
@@ -76,6 +119,39 @@ export function ThemeProvider({ children }: { children: ReactNode }) {
   );
 }
 
+/**
+ * Hook to access theme state and controls.
+ * Must be used within a ThemeProvider.
+ *
+ * @returns Theme context with mode, isDark flag, and control functions
+ * @throws Error if used outside of ThemeProvider
+ *
+ * @example
+ * ```tsx
+ * function SettingsScreen() {
+ *   const { mode, isDark, setMode, toggleTheme } = useTheme();
+ *
+ *   return (
+ *     <View>
+ *       <Text>Current mode: {mode}</Text>
+ *       <Text>Is dark: {isDark ? 'Yes' : 'No'}</Text>
+ *
+ *       <Button onPress={toggleTheme}>Toggle Theme</Button>
+ *
+ *       <Select
+ *         value={mode}
+ *         onValueChange={setMode}
+ *         options={[
+ *           { label: 'Light', value: 'light' },
+ *           { label: 'Dark', value: 'dark' },
+ *           { label: 'System', value: 'system' },
+ *         ]}
+ *       />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
 export function useTheme() {
   const context = useContext(ThemeContext);
   if (context === undefined) {