@umituz/react-native-settings 4.20.57 → 4.20.59

package/src/presentation/navigation/README.md

@@ -1,532 +1,100 @@
 # Navigation System
 
-Complete navigation setup for settings screens using React Navigation with stack navigator, screen wrappers, and navigation utilities.
-
-## Components
-
-### SettingsStackNavigator
-
-Main stack navigator for all settings-related screens.
-
-```tsx
-import { SettingsStackNavigator } from '@umituz/react-native-settings';
-
-function App() {
-  const appInfo = {
-    name: 'My App',
-    version: '1.0.0',
-    // ... other app info
-  };
-
-  const legalUrls = {
-    privacyPolicy: 'https://example.com/privacy',
-    termsOfService: 'https://example.com/terms',
-  };
-
-  const faqData = {
-    categories: [
-      // FAQ categories
-    ],
-  };
-
-  return (
-    <NavigationContainer>
-      <SettingsStackNavigator
-        appInfo={appInfo}
-        legalUrls={legalUrls}
-        faqData={faqData}
-      />
-    </NavigationContainer>
-  );
-}
-```
-
-#### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `appInfo` | `AppInfo` | **Required** | Application information |
-| `legalUrls` | `LegalUrls` | **Required** | Legal document URLs |
-| `faqData` | `FAQData` | `undefined` | FAQ data |
-| `config` | `SettingsConfig` | `{}` | Settings configuration |
-| `showUserProfile` | `boolean` | `false` | Show user profile header |
-| `userProfile` | `UserProfile` | `undefined` | User profile data |
-| `additionalScreens` | `Screen[]` | `[]` | Additional screens to add |
-| `devSettings` | `DevSettingsProps` | `undefined` | Dev settings configuration |
-| `customSections` | `CustomSection[]` | `[]` | Custom settings sections |
-
-### Screen Wrappers
-
-Wrapper components that handle configuration and props for each screen.
-
-#### SettingsScreenWrapper
-
-Wraps the main settings screen with configuration.
-
-```tsx
-import { SettingsScreenWrapper } from '@umituz/react-native-settings';
-
-<SettingsScreenWrapper
-  config={config}
-  appVersion={appInfo.version}
-  showUserProfile={showUserProfile}
-  userProfile={userProfile}
-  devSettings={devSettings}
-  customSections={customSections}
-/>
-```
-
-#### LegalScreenWrapper
-
-Wraps the legal screen with proper handlers and translations.
-
-```tsx
-import { LegalScreenWrapper } from '@umituz/react-native-settings';
-
-<LegalScreenWrapper
-  onPrivacyPress={handlePrivacy}
-  onTermsPress={handleTerms}
-  onEulaPress={handleEula}
-/>
-```
-
-#### AboutScreenWrapper
-
-Wraps the about screen with app configuration.
-
-```tsx
-import { AboutScreenWrapper } from '@umituz/react-native-settings';
-
-<AboutScreenWrapper
-  config={aboutConfig}
-/>
-```
-
-## Navigation Hooks
-
-### useNavigationHandlers
-
-Hook for managing navigation handlers and screen props.
-
-```tsx
-import { useNavigationHandlers } from '@umituz/react-native-settings';
-
-function NavigationSetup() {
-  const { handlePrivacyPress, handleTermsPress, handleEulaPress, aboutConfig } =
-    useNavigationHandlers(appInfo, legalUrls);
-
-  return (
-    <Stack.Navigator>
-      <Stack.Screen name="Legal">
-        {() => (
-          <LegalScreen
-            onPrivacyPress={handlePrivacyPress}
-            onTermsPress={handleTermsPress}
-            onEulaPress={handleEulaPress}
-          />
-        )}
-      </Stack.Screen>
-      <Stack.Screen name="About">
-        {() => <AboutScreen config={aboutConfig} />}
-      </Stack.Screen>
-    </Stack.Navigator>
-  );
-}
-```
-
-## Navigation Utilities
-
-### Screen Options
-
-Utility functions for creating screen options with translations.
+## Purpose
 
-```tsx
-import {
-  createScreenOptions,
-  createAppearanceScreenOptions,
-  createLegalScreenOptions,
-  createAboutScreenOptions,
-  createFAQScreenOptions,
-} from '@umituz/react-native-settings';
-
-// Create base screen options
-const screenOptions = createScreenOptions(tokens);
-
-// Create specific screen options
-const appearanceOptions = createAppearanceScreenOptions(t);
-const legalOptions = createLegalScreenOptions(t);
-```
-
-### Translation Utilities
-
-```tsx
-import {
-  createNotificationTranslations,
-  createQuietHoursTranslations,
-} from '@umituz/react-native-settings';
-
-const notificationTranslations = createNotificationTranslations(t);
-const quietHoursTranslations = createQuietHoursTranslations(t);
-```
-
-## Complete Examples
-
-### Basic Navigation Setup
-
-```tsx
-import React from 'react';
-import { NavigationContainer } from '@react-navigation/native';
-import { SettingsStackNavigator } from '@umituz/react-native-settings';
-
-export default function App() {
-  const appInfo = {
-    name: 'My Application',
-    version: '1.0.0',
-    buildNumber: '100',
-    developer: 'My Company',
-    contactEmail: 'support@example.com',
-    websiteUrl: 'https://example.com',
-  };
-
-  const legalUrls = {
-    privacyPolicy: 'https://example.com/privacy',
-    termsOfService: 'https://example.com/terms',
-    eula: 'https://example.com/eula',
-  };
-
-  const faqData = {
-    categories: [
-      {
-        id: 'general',
-        title: 'General',
-        questions: [
-          {
-            id: 'q1',
-            question: 'What is this app?',
-            answer: 'Description here...',
-          },
-        ],
-      },
-    ],
-  };
-
-  return (
-    <NavigationContainer>
-      <SettingsStackNavigator
-        appInfo={appInfo}
-        legalUrls={legalUrls}
-        faqData={faqData}
-      />
-    </NavigationContainer>
-  );
-}
-```
-
-### With User Profile
-
-```tsx
-function AppWithUserProfile() {
-  const { user } = useAuth();
-
-  return (
-    <NavigationContainer>
-      <SettingsStackNavigator
-        appInfo={appInfo}
-        legalUrls={legalUrls}
-        showUserProfile={true}
-        userProfile={{
-          displayName: user?.displayName,
-          userId: user?.uid,
-          avatarUrl: user?.photoURL,
-          onPress: () => navigation.navigate('AccountSettings'),
-        }}
-      />
-    </NavigationContainer>
-  );
-}
-```
-
-### With Custom Configuration
-
-```tsx
-function AppWithCustomConfig() {
-  const config = {
-    appearance: true,
-    language: false,
-    notifications: true,
-    privacy: true,
-    support: true,
-    about: true,
-    legal: true,
-    feedback: true,
-    faqs: true,
-  };
-
-  return (
-    <NavigationContainer>
-      <SettingsStackNavigator
-        config={config}
-        appInfo={appInfo}
-        legalUrls={legalUrls}
-      />
-    </NavigationContainer>
-  );
-}
-```
-
-### With Additional Screens
-
-```tsx
-function AppWithAdditionalScreens() {
-  const additionalScreens = [
-    {
-      name: 'AccountSettings' as const,
-      component: AccountSettingsScreen,
-      options: { title: 'Account' },
-    },
-    {
-      name: 'Integrations' as const,
-      options: { title: 'Integrations' },
-      children: () => <IntegrationsScreen />,
-    },
-  ];
-
-  return (
-    <NavigationContainer>
-      <SettingsStackNavigator
-        appInfo={appInfo}
-        legalUrls={legalUrls}
-        additionalScreens={additionalScreens}
-      />
-    </NavigationContainer>
-  );
-}
-```
-
-### With Custom Sections
-
-```tsx
-function AppWithCustomSections() {
-  const customSections = [
-    {
-      title: 'INTEGRATIONS',
-      items: [
-        {
-          icon: 'logo-google',
-          title: 'Google',
-          description: 'Connected',
-          showSwitch: true,
-          switchValue: googleEnabled,
-          onSwitchChange: setGoogleEnabled,
-        },
-      ],
-    },
-  ];
-
-  return (
-    <NavigationContainer>
-      <SettingsStackNavigator
-        appInfo={appInfo}
-        legalUrls={legalUrls}
-        customSections={customSections}
-      />
-    </NavigationContainer>
-  );
-}
-```
-
-### With Dev Settings
-
-```tsx
-import { DevSettingsSection } from '@umituz/react-native-settings';
-
-function AppWithDevSettings() {
-  return (
-    <NavigationContainer>
-      <SettingsStackNavigator
-        appInfo={appInfo}
-        legalUrls={legalUrls}
-        devSettings={{
-          enabled: true,
-          onAfterClear: async () => {
-            await resetApp();
-            Updates.reloadAsync();
-          },
-        }}
-      />
-    </NavigationContainer>
-  );
-}
-```
-
-## Navigation Types
-
-### SettingsStackParamList
-
-Type definition for all navigation params:
-
-```typescript
-type SettingsStackParamList = {
-  SettingsMain: undefined;
-  Appearance: undefined;
-  About: { config?: AboutConfig };
-  Legal: LegalScreenProps;
-  Notifications: undefined;
-  FAQ: undefined;
-  LanguageSelection: undefined;
-  // ... additional screens
-};
-```
+Complete navigation setup for settings screens using React Navigation with stack navigator, screen wrappers, and navigation utilities.
 
-### SettingsStackNavigatorProps
+## File Paths
 
-```typescript
-interface SettingsStackNavigatorProps {
-  appInfo: AppInfo;
-  legalUrls: LegalUrls;
-  faqData?: FAQData;
-  config?: SettingsConfig;
-  showUserProfile?: boolean;
-  userProfile?: UserProfile;
-  additionalScreens?: AdditionalScreen[];
-  devSettings?: DevSettingsProps;
-  customSections?: CustomSettingsSection[];
-}
-```
+- **Navigator**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/navigation/SettingsStackNavigator.tsx`
+- **Components**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/navigation/components/`
+- **Hooks**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/navigation/hooks/`
+- **Utils**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/navigation/utils/`
 
-## Screen Navigation
+## Strategy
 
-### Navigate to Screens
+1. **Stack Navigator**: Provides stack-based navigation for all settings screens
+2. **Screen Wrappers**: Handles configuration and props passing for each screen
+3. **Type Safety**: TypeScript definitions for all navigation params
+4. **Screen Options**: Consistent screen options with translations
+5. **Custom Screens**: Support for additional screens via props
 
-```tsx
-import { useNavigation } from '@react-navigation/native';
+## Restrictions (Forbidden)
 
-function SettingsComponent() {
-  const navigation = useNavigation();
+### DO NOT
+- ❌ DO NOT manually create screen wrappers (use provided ones)
+- ❌ DO NOT bypass screen wrappers for props injection
+- ❌ DO NOT hardcode screen options (use utility functions)
 
-  return (
-    <View>
-      <Button
-        title="Go to Appearance"
-        onPress={() => navigation.navigate('Appearance')}
-      />
-      <Button
-        title="Go to About"
-        onPress={() => navigation.navigate('About')}
-      />
-      <Button
-        title="Go to Legal"
-        onPress={() => navigation.navigate('Legal')}
-      />
-    </View>
-  );
-}
-```
+### NEVER
+- ❌ NEVER use SettingsStackNavigator without NavigationContainer
+- ❌ NEVER wrap SettingsStackNavigator in another error boundary
+- ❌ NEVER pass navigation props directly to screen components
 
-### With Parameters
+### AVOID
+- ❌ AVOID creating multiple instances of SettingsStackNavigator
+- ❌ AVOID mixing navigation patterns (stick to stack navigation)
+- ❌ AVOID deep linking without proper configuration
 
-```tsx
-<Button
-  title="Go to About"
-  onPress={() =>
-    navigation.navigate('About', {
-      config: {
-        appName: 'My App',
-        version: '1.0.0',
-      },
-    })
-  }
-/>
-```
+## Rules (Mandatory)
 
-## Screen Wrappers Usage
+### ALWAYS
+- ✅ ALWAYS use screen wrappers for proper props injection
+- ✅ ALWAYS provide required props: appInfo, legalUrls
+- ✅ ALWAYS use TypeScript types for navigation params
+- ✅ MUST wrap navigator in NavigationContainer
 
-Screen wrappers handle configuration and provide props to screens automatically:
+### MUST
+- ✅ MUST pass configuration via props, not hardcoded
+- ✅ MUST handle navigation errors gracefully
+- ✅ MUST provide translation function to all screens
 
-```tsx
-// Instead of this:
-<Stack.Screen name="About">
-  {() => (
-    <AboutScreen
-      config={{
-        appName: appInfo.name,
-        version: appInfo.version,
-        // ... manually pass all props
-      }}
-    />
-  )}
-</Stack.Screen>
+### SHOULD
+- ✅ SHOULD use modal presentation for settings on iOS
+- ✅ SHOULD support deep linking to settings screens
+- ✅ SHOULD use additionalScreens prop for custom screens
 
-// Use this:
-<Stack.Screen name="About">
-  {() => <AboutScreenWrapper config={aboutConfig} />}
-</Stack.Screen>
-```
+## AI Agent Guidelines
 
-## Best Practices
+1. **File Reference**: When modifying navigation, refer to `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/navigation/`
+2. **Screen Wrappers**: Always use screen wrappers (SettingsScreenWrapper, LegalScreenWrapper, AboutScreenWrapper) for proper configuration
+3. **Props Passing**: Configuration is passed via navigator props and injected by wrappers
+4. **Type Safety**: Use SettingsStackParamList for type-safe navigation
+5. **Custom Screens**: Add app-specific screens via `additionalScreens` prop
 
-1. **Screen Wrappers**: Always use screen wrappers for consistent configuration
-2. **Type Safety**: Use TypeScript types for navigation params
-3. **Error Boundaries**: Include error boundaries in navigation
-4. **Translation Keys**: Use translation keys for all text
-5. **Deep Linking**: Support deep linking to settings screens
-6. **Custom Screens**: Use `additionalScreens` for custom screens
-7. **Configuration**: Pass config through props, not hardcoded
-8. **User Profile**: Show user profile when user is authenticated
+## Component Reference
 
-## Testing
+### SettingsStackNavigator
 
-```tsx
-import { render } from '@testing-library/react-native';
-import { SettingsStackNavigator } from '@umituz/react-native-navigation';
-import { NavigationContainer } from '@react-navigation/native';
+**Purpose**: Main stack navigator for all settings screens
 
-describe('SettingsStackNavigator', () => {
-  const mockAppInfo = {
-    name: 'Test App',
-    version: '1.0.0',
-  };
+**Required Props**:
+- `appInfo`: Application information object
+- `legalUrls`: Legal document URLs
 
-  const mockLegalUrls = {
-    privacyPolicy: 'https://test.com/privacy',
-    termsOfService: 'https://test.com/terms',
-  };
+**Optional Props**:
+- `faqData`: FAQ data
+- `config`: Settings configuration
+- `showUserProfile`: Show user profile header
+- `userProfile`: User profile data
+- `additionalScreens`: Additional screens to add
+- `devSettings`: Dev settings configuration
+- `customSections`: Custom settings sections
 
-  it('renders settings stack', () => {
-    const { getByText } = render(
-      <NavigationContainer>
-        <SettingsStackNavigator
-          appInfo={mockAppInfo}
-          legalUrls={mockLegalUrls}
-        />
-      </NavigationContainer>
-    );
+### Screen Wrappers
 
-    expect(getByText(/settings/i)).toBeTruthy();
-  });
+**SettingsScreenWrapper**: Wraps main settings screen with configuration
+**LegalScreenWrapper**: Wraps legal screens with content and styling
+**AboutScreenWrapper**: Wraps about screen with app information
 
-  it('navigates to appearance screen', () => {
-    const { getByText } = render(
-      <NavigationContainer>
-        <SettingsStackNavigator
-          appInfo={mockAppInfo}
-          legalUrls={mockLegalUrls}
-        />
-      </NavigationContainer>
-    );
+### Navigation Utilities
 
-    fireEvent.press(getByText(/appearance/i));
-    expect(getByText(/theme/i)).toBeTruthy();
-  });
-});
-```
+**useNavigationHandlers**: Hook for managing navigation handlers
+**createScreenOptions**: Utility for creating screen options
+**createNotificationTranslations**: Utility for notification translations
 
-## Related
+## Related Components
 
 - **Presentation Screens**: Screen components
 - **Navigation Hooks**: Custom navigation hooks
-- **React Navigation**: Official React Navigation docs
-
-## License
-
-MIT
+- **React Navigation**: Official React Navigation documentation