@umituz/react-native-settings 4.20.57 → 4.20.59

package/src/presentation/screens/hooks/README.md

@@ -1,383 +1,93 @@
-# useFeatureDetection Hook
+# Settings Screen Hooks
 
-Hook for automatically detecting which settings features should be shown based on configuration and navigation state.
+## Purpose
 
-## Features
+Custom React hooks for settings screen feature detection, configuration normalization, and navigation management.
 
-- **Auto Detection**: Automatically detects available screens
-- **Config Override**: Respects explicit enabled/disabled flags
-- **Service Check**: Checks for required services (e.g., notifications)
-- **Navigation Check**: Verifies screen exists in navigation stack
-- **Memoized**: Optimized with useMemo for performance
+## File Paths
 
-## Installation
+- **Feature Detection**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/screens/hooks/useFeatureDetection.ts`
+- **Config Utils**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/screens/utils/normalizeConfig.ts`
 
-This hook is part of `@umituz/react-native-settings`.
+## Strategy
 
-## Usage
+1. **Auto Detection**: Automatically detects available screens based on navigation state
+2. **Config Normalization**: Converts various config formats to consistent structure
+3. **Feature Flags**: Generates boolean flags for each feature based on config and availability
+4. **Performance Optimization**: Uses useMemo to prevent unnecessary recalculations
+5. **Service Integration**: Checks for required services (e.g., notifications)
 
-### Basic Usage
+## Restrictions (Forbidden)
 
-```tsx
-import { useFeatureDetection } from '@umituz/react-native-settings';
+### DO NOT
+- ❌ DO NOT use raw config without normalizing first
+- ❌ DO NOT bypass feature detection for dynamic features
+- ❌ DO NOT mutate normalized config objects
 
-function MySettingsScreen() {
-  const navigation = useNavigation();
-  const normalizedConfig = normalizeSettingsConfig(config);
+### NEVER
+- ❌ NEVER hardcode feature availability (use detection)
+- ❌ NEVER use feature flags without first normalizing config
+- ❌ NEVER rely on auto-detection for must-show features
 
-  const features = useFeatureDetection(normalizedConfig, navigation);
+### AVOID
+- ❌ AVOID changing config structure after normalization
+- ❌ AVOID unnecessary hook re-renders by keeping dependencies stable
+- ❌ AVOID mixing auto-detection with explicit booleans inconsistently
 
-  return (
-    <View>
-      {features.appearance && <Text>Appearance is available</Text>}
-      {features.language && <Text>Language is available</Text>}
-    </View>
-  );
-}
-```
+## Rules (Mandatory)
 
-## API
+### ALWAYS
+- ✅ ALWAYS normalize config before passing to components or hooks
+- ✅ ALWAYS use useFeatureDetection for dynamic features
+- ✅ ALWAYS provide stable navigation reference to hooks
+- ✅ MUST use memoization for performance optimization
 
-### Parameters
+### MUST
+- ✅ MUST check navigation state for screen availability
+- ✅ MUST respect explicit enabled/disabled flags in config
+- ✅ MUST provide service availability for features that require it
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `normalizedConfig` | `NormalizedConfig` | Normalized configuration object |
-| `navigation` | `NavigationProp` | React Navigation object |
-| `options` | `DetectionOptions` | Optional detection options |
+### SHOULD
+- ✅ SHOULD use 'auto' for features that should be conditionally shown
+- ✅ SHOULD use boolean for must-show/must-hide features
+- ✅ SHOULD keep feature detection logic in hooks, not components
 
-### DetectionOptions
+## AI Agent Guidelines
 
-```typescript
-interface DetectionOptions {
-  notificationServiceAvailable?: boolean;
-}
-```
+1. **File Reference**: When modifying feature detection, refer to `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/screens/hooks/useFeatureDetection.ts`
+2. **Normalization**: Always call `normalizeSettingsConfig()` before using config
+3. **Feature Types**: Understand three config types: boolean (true/false), 'auto' (detect), or object (advanced)
+4. **Navigation Checks**: Auto-detection checks if screen exists in navigation stack
+5. **Service Checks**: Some features (notifications) require service availability checks
 
-### Returns
+## Hook Reference
 
-```typescript
-interface FeatureFlags {
-  appearance: boolean;     // Is appearance screen available?
-  language: boolean;       // Is language screen available?
-  notifications: boolean;  // Are notifications available?
-  about: boolean;          // Is about screen available?
-  legal: boolean;          // Is legal screen available?
-  disclaimer: boolean;     // Is disclaimer available?
-  userProfile: boolean;    // Should show user profile?
-  feedback: boolean;       // Is feedback available?
-  rating: boolean;         // Is rating available?
-  faqs: boolean;           // Are FAQs available?
-  subscription: boolean;   // Is subscription available?
-  wallet: boolean;         // Is wallet available?
-}
-```
+### useFeatureDetection
 
-## Detection Logic
+**Purpose**: Detects which features should be shown based on config and navigation state
 
-### Auto Detection Algorithm
+**Parameters**:
+- `normalizedConfig`: Normalized configuration object
+- `navigation`: React Navigation object
+- `options`: Detection options (e.g., notificationServiceAvailable)
 
-For each feature:
+**Returns**: FeatureFlags object with boolean flags for each feature
 
-```typescript
-function shouldShowFeature(
-  normalizedConfig,
-  navigation,
-  options
-): boolean {
-  const { enabled, config } = normalizedConfig;
+**Usage**: Use in SettingsScreen or SettingsContent to control section visibility
 
-  // Check normalized enabled flag
-  if (!enabled) return false;
+### normalizeSettingsConfig
 
-  // Explicit override in config object
-  if (config?.enabled === true) return true;
-  if (config?.enabled === false) return false;
+**Purpose**: Converts raw config to normalized format with enabled flags and config objects
 
-  // Auto-detect based on navigation
-  const defaultRoute = getDefaultRoute(feature);
-  return hasNavigationScreen(navigation, defaultRoute);
-}
-```
+**Parameters**:
+- `config`: Raw SettingsConfig object
 
-### Navigation Screen Check
+**Returns**: NormalizedConfig with consistent structure
 
-```typescript
-function hasNavigationScreen(
-  navigation: any,
-  screenName: string
-): boolean {
-  try {
-    const state = navigation.getState();
-    if (!state) return false;
+**Usage**: Always call before passing config to components or hooks
 
-    const checkRoutes = (routes: any[]): boolean => {
-      for (const route of routes) {
-        if (route.name === screenName) return true;
-        if (route.state?.routes && checkRoutes(route.state.routes)) {
-          return true;
-        }
-      }
-      return false;
-    };
+## Related Components
 
-    return checkRoutes(state.routes || []);
-  } catch {
-    return false;
-  }
-}
-```
-
-## Examples
-
-### With Auto Detection
-
-```tsx
-function AutoDetectedSettings() {
-  const navigation = useNavigation();
-  const config = {
-    appearance: 'auto',  // Will detect Appearance screen
-    language: 'auto',    // Will detect Language screen
-    notifications: 'auto', // Will detect Notifications screen
-  };
-
-  const normalized = normalizeSettingsConfig(config);
-  const features = useFeatureDetection(normalized, navigation);
-
-  return (
-    <SettingsContent
-      normalizedConfig={normalized}
-      features={features}
-    />
-  );
-}
-```
-
-### With Service Check
-
-```tsx
-function SettingsWithServiceCheck() {
-  const navigation = useNavigation();
-  const notificationServiceAvailable = true; // From app state
-
-  const features = useFeatureDetection(normalizedConfig, navigation, {
-    notificationServiceAvailable,
-  });
-
-  // notifications will only be true if:
-  // 1. enabled in config
-  // 2. notificationServiceAvailable is true
-  // 3. Notifications screen exists
-}
-```
-
-### With Custom Routes
-
-```tsx
-function SettingsWithCustomRoutes() {
-  const config = {
-    appearance: {
-      enabled: true,
-      route: 'CustomAppearance',  // Custom screen name
-    },
-    language: {
-      enabled: true,
-      route: 'LanguagePicker',     // Custom screen name
-    },
-  };
-
-  const features = useFeatureDetection(
-    normalizeSettingsConfig(config),
-    navigation
-  );
-}
-```
-
-### Explicit Enable/Disable
-
-```tsx
-function ExplicitlyConfiguredSettings() {
-  const config = {
-    appearance: true,           // Always show
-    language: false,             // Never show
-    notifications: {
-      enabled: true,             // Explicitly enabled
-      route: 'Notifications',    // Will check this route
-    },
-    about: {
-      enabled: false,            // Explicitly disabled
-      route: 'About',            // Won't check even if exists
-    },
-  };
-
-  const features = useFeatureDetection(
-    normalizeSettingsConfig(config),
-    navigation
-  );
-
-  // features.appearance === true
-  // features.language === false
-  // features.notifications === (has Notifications screen)
-  // features.about === false
-}
-```
-
-### Combined Configuration
-
-```tsx
-function MixedConfiguration() {
-  const config = {
-    // Simple boolean
-    appearance: true,
-
-    // Auto-detect
-    language: 'auto',
-
-    // Advanced with explicit enabled
-    notifications: {
-      enabled: true,
-      route: 'Notifications',
-      showQuietHours: true,
-    },
-
-    // Advanced with auto-detection
-    about: {
-      enabled: 'auto',
-      route: 'About',
-    },
-
-    // Explicitly disabled
-    legal: false,
-  };
-
-  const features = useFeatureDetection(
-    normalizeSettingsConfig(config),
-    navigation
-  );
-}
-```
-
-## Default Routes
-
-Default screen routes checked for each feature:
-
-| Feature | Default Route |
-|---------|--------------|
-| `appearance` | `'Appearance'` |
-| `language` | `'LanguageSelection'` |
-| `notifications` | `'Notifications'` |
-| `about` | `'About'` |
-| `legal` | `'Legal'` |
-| `disclaimer` | `'Disclaimer'` |
-
-## Feature-Specific Logic
-
-### Notifications
-
-```typescript
-notifications: notifications.enabled && (
-  notifications.config?.enabled === true ||
-  (notifications.config?.enabled !== false &&
-    notificationServiceAvailable &&
-    hasNavigationScreen(navigation, 'Notifications'))
-)
-```
-
-Requires both:
-- Service availability check
-- Navigation screen check
-
-### Profile, Feedback, Rating, FAQs
-
-These features don't check navigation:
-
-```typescript
-userProfile: userProfile.enabled,
-feedback: feedback.enabled,
-rating: rating.enabled,
-faqs: faqs.enabled,
-```
-
-## Performance
-
-### Memoization
-
-The hook uses `useMemo` to prevent unnecessary recalculations:
-
-```typescript
-const features = useMemo(() => {
-  // Detection logic
-}, [normalizedConfig, navigation, options]);
-```
-
-### Dependencies
-
-Recalculates when:
-- `normalizedConfig` changes
-- `navigation` changes (should be stable)
-- `options` changes
-
-## Best Practices
-
-1. **Normalize First**: Always normalize config before passing to hook
-2. **Use Auto**: Prefer `'auto'` for automatic detection
-3. **Service Checks**: Provide service availability in options
-4. **Custom Routes**: Define custom routes in config objects
-5. **Explicit Flags**: Use boolean for must-show/must-hide features
-6. **Stable Navigation**: Pass stable navigation reference
-7. **Memoization**: Hook is already memoized for performance
-
-## Testing
-
-```tsx
-import { renderHook } from '@testing-library/react-native';
-import { useFeatureDetection } from '@umituz/react-native-settings';
-
-describe('useFeatureDetection', () => {
-  it('detects available screens', () => {
-    const navigation = {
-      getState: () => ({
-        routes: [
-          { name: 'Appearance' },
-          { name: 'LanguageSelection' },
-        ],
-      }),
-    };
-
-    const config = {
-      appearance: 'auto',
-      language: 'auto',
-      notifications: 'auto',
-    };
-
-    const { result } = renderHook(() =>
-      useFeatureDetection(normalizeSettingsConfig(config), navigation)
-    );
-
-    expect(result.current.appearance).toBe(true);
-    expect(result.current.language).toBe(true);
-  });
-
-  it('respects explicit disabled', () => {
-    const config = {
-      appearance: false,  // Explicitly disabled
-    };
-
-    const { result } = renderHook(() =>
-      useFeatureDetection(normalizeSettingsConfig(config), navigation)
-    );
-
-    expect(result.current.appearance).toBe(false);
-  });
-});
-```
-
-## Related
-
-- **normalizeSettingsConfig**: Config normalization
-- **SettingsContent**: Content component
-- **Feature Detection**: Detection utility functions
-
-## License
-
-MIT
+- **SettingsScreen**: Main screen that uses these hooks
+- **SettingsContent**: Content component that uses feature flags
+- **Navigation Utils**: Helper functions for navigation checks