@umituz/react-native-settings 4.20.58 → 4.20.59

package/src/presentation/navigation/utils/README.md

@@ -1,442 +1,162 @@
 # Navigation Utilities
 
-Utility functions and helpers for managing navigation in the settings system, including screen options, params handling, and navigation helpers.
-
-## Utilities
-
-### getDefaultRoute
-
-Gets the default route name for a given feature.
-
-```typescript
-import { getDefaultRoute } from '@umituz/react-native-settings';
+## Purpose
 
-const route = getDefaultRoute('appearance');
-// Returns: 'Appearance'
-
-const route = getDefaultRoute('language');
-// Returns: 'LanguageSelection'
-```
-
-#### Signature
+Utility functions and helpers for managing navigation in the settings system, including screen options, params handling, and navigation helpers.
 
-```typescript
-function getDefaultRoute(feature: keyof DefaultRoutes): string;
-```
+## File Paths
 
-#### Default Routes
+- **Navigation Utils**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/navigation/utils/navigationHelpers.ts`
+- **Screen Options**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/navigation/utils/screenOptions.ts`
 
-| Feature | Route |
-|---------|-------|
-| `appearance` | `'Appearance'` |
-| `language` | `'LanguageSelection'` |
-| `notifications` | `'Notifications'` |
-| `about` | `'About'` |
-| `legal` | `'Legal'` |
-| `disclaimer` | `'Disclaimer'` |
+## Strategy
 
-### hasNavigationScreen
+1. **Screen Detection**: Checks if screens exist in navigation state
+2. **Route Mapping**: Maps features to default route names
+3. **Safe Navigation**: Provides safe navigation with error handling
+4. **Param Validation**: Validates and sanitizes navigation params
+5. **State Helpers**: Utilities for navigation state inspection
 
-Checks if a screen exists in the current navigation state.
+## Restrictions (Forbidden)
 
-```typescript
-import { hasNavigationScreen } from '@umituz/react-native-settings';
+### DO NOT
+- ❌ DO NOT use hardcoded route names (use getDefaultRoute)
+- ❌ DO NOT bypass screen availability checks
+- ❌ DO NOT navigate without validating params
 
-const navigation = useNavigation();
-const hasAppearance = hasNavigationScreen(navigation, 'Appearance');
-// Returns: true if 'Appearance' screen exists in navigation
-```
-
-#### Signature
-
-```typescript
-function hasNavigationScreen(navigation: any, screenName: string): boolean;
-```
-
-#### Example
-
-```tsx
-function SettingsButton() {
-  const navigation = useNavigation();
-
-  const handlePress = useCallback(() => {
-    if (hasNavigationScreen(navigation, 'Appearance')) {
-      navigation.navigate('Appearance');
-    } else {
-      console.warn('Appearance screen not found');
-    }
-  }, [navigation]);
-
-  return <Button onPress={handlePress} title="Appearance" />;
-}
-```
-
-### createSettingsScreenOptions
-
-Creates screen options configuration for settings screens.
-
-```typescript
-import { createSettingsScreenOptions } from '@umituz/react-native-settings';
-
-const options = createSettingsScreenOptions({
-  title: 'Appearance',
-  showHeader: true,
-  headerStyle: { backgroundColor: '#fff' },
-});
-```
-
-#### Signature
-
-```typescript
-function createSettingsScreenOptions(config: {
-  title?: string;
-  showHeader?: boolean;
-  headerStyle?: any;
-  headerTintColor?: string;
-  headerTitleStyle?: any;
-}): any;
-```
-
-### getLegalDocumentType
-
-Extracts document type from route params or returns default.
-
-```typescript
-import { getLegalDocumentType } from '@umituz/react-native-settings';
-
-const documentType = getLegalDocumentType(route.params);
-// Returns: 'privacy-policy' | 'terms-of-service' | 'eula'
-```
-
-#### Signature
-
-```typescript
-function getLegalDocumentType(params: any): LegalDocumentType;
-```
-
-## Screen Options Helpers
-
-### Default Screen Options
-
-```typescript
-const defaultScreenOptions = {
-  headerStyle: {
-    backgroundColor: tokens.colors.surface,
-  },
-  headerTintColor: tokens.colors.textPrimary,
-  headerTitleStyle: {
-    fontWeight: '600',
-    fontSize: 17,
-  },
-  cardStyle: {
-    backgroundColor: tokens.colors.background,
-  },
-};
-```
-
-### Modal Screen Options
-
-```typescript
-const modalScreenOptions = {
-  presentation: 'modal',
-  headerShown: false,
-  cardStyle: {
-    backgroundColor: 'transparent',
-  },
-  cardOverlayEnabled: true,
-  cardStyleInterpolator: CardStyleInterpolators.forVerticalIOS,
-};
-```
-
-### Settings Screen Options
-
-```typescript
-const settingsScreenOptions = {
-  headerShown: false,
-  gestureEnabled: true,
-  cardStyle: {
-    backgroundColor: tokens.colors.background,
-  },
-};
-```
-
-## Navigation Param Helpers
+### NEVER
+- ❌ NEVER use navigation.navigate() without checking screen availability
+- ❌ NEVER pass invalid or unsafe params to navigation
+- ❌ NEVER assume navigation state is valid
 
-### validateParams
+### AVOID
+- ❌ AVOID complex navigation state parsing (use provided helpers)
+- ❌ AVOID navigation without error handling
+- ❌ AVOID manual route name construction
 
-Validates navigation params for a given screen.
+## Rules (Mandatory)
 
-```typescript
-import { validateParams } from '@umituz/react-native-settings';
+### ALWAYS
+- ✅ ALWAYS use safeNavigate for error-prone navigation
+- ✅ ALWAYS check screen availability before navigation
+- ✅ MUST validate params before navigation
+- ✅ MUST handle navigation errors gracefully
 
-const isValid = validateParams('Appearance', {
-  showThemeSection: true,
-  showColorsSection: false,
-});
-// Returns: true
-```
+### MUST
+- ✅ MUST use getDefaultRoute for default route names
+- ✅ MUST use hasNavigationScreen for availability checks
+- ✅ MUST provide fallback routes for custom navigation
 
-#### Signature
+### SHOULD
+- ✅ SHOULD use navigateWithFallback for custom routes
+- ✅ SHOULD track navigation events for analytics
+- ✅ SHOULD validate all navigation params
 
-```typescript
-function validateParams(screen: string, params: any): boolean;
-```
+## AI Agent Guidelines
 
-### sanitizeParams
+1. **File Reference**: When modifying navigation utilities, refer to `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/navigation/utils/`
+2. **Screen Detection**: Always use hasNavigationScreen before navigating to dynamic screens
+3. **Route Mapping**: Use getDefaultRoute for default route names, don't hardcode
+4. **Safe Navigation**: Use safeNavigate for all navigation with error handling
+5. **Param Validation**: Always validate params before navigation
 
-Sanitizes and removes invalid params for navigation.
+## Utility Reference
 
-```typescript
-import { sanitizeParams } from '@umituz/react-native-settings';
+### getDefaultRoute
 
-const cleanParams = sanitizeParams('Appearance', {
-  showThemeSection: true,
-  invalidParam: 'should be removed',
-});
-// Returns: { showThemeSection: true }
-```
+**Purpose**: Gets default route name for a feature
 
-#### Signature
+**Parameters**:
+- `feature`: Feature name (keyof DefaultRoutes)
 
-```typescript
-function sanitizeParams(screen: string, params: any): any;
-```
+**Returns**: Default route name string
 
-## Navigation State Helpers
+**Example**: `getDefaultRoute('appearance')` returns `'Appearance'`
 
-### getActiveRouteName
+**Usage**: Use when you need default route for a feature
 
-Gets the name of the currently active route.
+### hasNavigationScreen
 
-```typescript
-import { getActiveRouteName } from '@umituz/react-native-settings';
+**Purpose**: Checks if screen exists in navigation state
 
-const navigation = useNavigation();
-const currentRoute = getActiveRouteName(navigation);
-// Returns: 'Appearance'
-```
+**Parameters**:
+- `navigation`: React Navigation object
+- `screenName`: Screen name to check
 
-#### Signature
+**Returns**: Boolean indicating screen availability
 
-```typescript
-function getActiveRouteName(navigation: any): string;
-```
+**Example**: `hasNavigationScreen(navigation, 'Appearance')`
 
-#### Example
+**Usage**: Always check before navigating to dynamic screens
 
-```tsx
-function SettingsScreen() {
-  const navigation = useNavigation();
-  const currentRoute = getActiveRouteName(navigation);
+### safeNavigate
 
-  useFocusEffect(
-    useCallback(() => {
-      Analytics.trackScreen(currentRoute);
-    }, [currentRoute])
-  );
+**Purpose**: Safely navigates with error handling
 
-  return <SettingsContent />;
-}
-```
+**Parameters**:
+- `navigation`: React Navigation object
+- `routeName`: Target route name
+- `params?`: Navigation parameters
 
-### getNavigationDepth
+**Returns**: Boolean success indicator
 
-Gets the depth of the current navigation stack.
+**Example**: `safeNavigate(navigation, 'Appearance', config)`
 
-```typescript
-import { getNavigationDepth } from '@umituz/react-native-settings';
+**Usage**: Use for all navigation that might fail
 
-const depth = getNavigationDepth(navigation);
-// Returns: 3 (three screens in stack)
-```
+### navigateWithFallback
 
-#### Signature
+**Purpose**: Navigates with fallback route if primary doesn't exist
 
-```typescript
-function getNavigationDepth(navigation: any): number;
-```
+**Parameters**:
+- `navigation`: React Navigation object
+- `primaryRoute`: Try this route first
+- `fallbackRoute`: Use this if primary doesn't exist
+- `params?`: Navigation parameters
 
-### canGoBack
+**Returns**: void
 
-Checks if navigation can go back.
+**Example**: `navigateWithFallback(navigation, 'CustomAppearance', 'Appearance', config)`
 
-```typescript
-import { canGoBack } from '@umituz/react-native-settings';
+**Usage**: Use when supporting custom routes with defaults
 
-if (canGoBack(navigation)) {
-  navigation.goBack();
-}
-```
+### getActiveRouteName
 
-#### Signature
+**Purpose**: Gets currently active route name
 
-```typescript
-function canGoBack(navigation: any): boolean;
-```
+**Parameters**:
+- `navigation`: React Navigation object
 
-## Navigation Action Helpers
+**Returns**: Current route name string
 
-### safeNavigate
+**Usage**: Use for analytics or tracking
 
-Safely navigates to a screen with error handling.
+### validateParams
 
-```typescript
-import { safeNavigate } from '@umituz/react-native-settings';
+**Purpose**: Validates navigation params for a screen
 
-safeNavigate(navigation, 'Appearance', { showThemeSection: true });
-```
+**Parameters**:
+- `screen`: Screen name
+- `params`: Params object to validate
 
-#### Signature
+**Returns**: Boolean validity indicator
 
-```typescript
-function safeNavigate(
-  navigation: any,
-  routeName: string,
-  params?: any
-): boolean;
-```
+**Usage**: Always validate before navigation
 
-#### Example
+### sanitizeParams
 
-```tsx
-function NavigateButton() {
-  const navigation = useNavigation();
+**Purpose**: Removes invalid params from navigation params
 
-  const handlePress = () => {
-    const success = safeNavigate(navigation, 'Appearance');
-    if (!success) {
-      Alert.alert('Error', 'Could not navigate to Appearance');
-    }
-  };
+**Parameters**:
+- `screen`: Screen name
+- `params`: Params object to sanitize
 
-  return <Button onPress={handlePress} title="Go to Appearance" />;
-}
-```
+**Returns**: Sanitized params object
 
-### navigateWithFallback
+**Usage**: Use to clean params before navigation
 
-Navigates to a screen with a fallback route if the primary doesn't exist.
-
-```typescript
-import { navigateWithFallback } from '@umituz/react-native-settings';
-
-navigateWithFallback(
-  navigation,
-  'CustomAppearance',  // Try this first
-  'Appearance'          // Fallback to this
-);
-```
-
-#### Signature
-
-```typescript
-function navigateWithFallback(
-  navigation: any,
-  primaryRoute: string,
-  fallbackRoute: string,
-  params?: any
-): void;
-```
-
-## Usage Examples
-
-### Feature Detection Navigation
-
-```tsx
-function AutoNavigateButton() {
-  const navigation = useNavigation();
-
-  const handlePress = useCallback(() => {
-    // Try custom route first, fallback to default
-    const customRoute = config?.appearance?.route || 'Appearance';
-    navigateWithFallback(navigation, customRoute, 'Appearance', config);
-  }, [navigation, config]);
-
-  return <Button onPress={handlePress} title="Appearance" />;
-}
-```
-
-### Conditional Navigation
-
-```tsx
-function ConditionalNavigation() {
-  const navigation = useNavigation();
-
-  const navigateToScreen = useCallback((screenName: string) => {
-    if (hasNavigationScreen(navigation, screenName)) {
-      safeNavigate(navigation, screenName);
-    } else {
-      console.warn(`Screen ${screenName} not available`);
-    }
-  }, [navigation]);
-
-  return (
-    <View>
-      <Button onPress={() => navigateToScreen('Appearance')} title="Appearance" />
-      <Button onPress={() => navigateToScreen('Language')} title="Language" />
-    </View>
-  );
-}
-```
-
-### Navigation Analytics
-
-```tsx
-function useNavigationTracking() {
-  const navigation = useNavigation();
-  const currentRoute = getActiveRouteName(navigation);
-
-  useEffect(() => {
-    const unsubscribe = navigation.addListener('state', () => {
-      const route = getActiveRouteName(navigation);
-      Analytics.trackScreen(route);
-    });
-
-    return unsubscribe;
-  }, [navigation]);
-
-  return currentRoute;
-}
-```
-
-### Param Validation
-
-```tsx
-function ValidatedNavigation() {
-  const navigation = useNavigation();
-
-  const handleNavigate = useCallback(() => {
-    const params = {
-      showThemeSection: true,
-      showColorsSection: true,
-    };
-
-    if (validateParams('Appearance', params)) {
-      navigation.navigate('Appearance', params);
-    } else {
-      Alert.alert('Error', 'Invalid parameters');
-    }
-  }, [navigation]);
-
-  return <Button onPress={handleNavigate} title="Appearance" />;
-}
-```
-
-## Best Practices
-
-1. **Validation**: Always validate params before navigation
-2. **Fallbacks**: Provide fallback routes for custom navigation
-3. **Error Handling**: Use safeNavigate for error-prone navigation
-4. **Screen Detection**: Check for screen existence before navigation
-5. **Analytics**: Track navigation events for insights
-6. **Type Safety**: Use TypeScript for all navigation utilities
-
-## Related
+## Related Components
 
 - **Navigation Hooks**: Custom navigation hooks
 - **Navigation Components**: Screen wrappers
 - **React Navigation**: Official navigation library
-
-## License
-
-MIT