@umituz/react-native-settings 4.20.57 → 4.20.59

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

@@ -1,439 +1,109 @@
 # Settings Screen Types
 
-TypeScript type definitions for settings screen configuration, components, and utilities.
-
-## Types
-
-### SettingsConfig
-
-Main configuration object for the settings screen.
-
-```typescript
-interface SettingsConfig {
-  appearance?: FeatureVisibility | AppearanceConfig;
-  language?: FeatureVisibility | LanguageConfig;
-  notifications?: FeatureVisibility | NotificationsConfig;
-  about?: FeatureVisibility | AboutConfig;
-  legal?: FeatureVisibility | LegalConfig;
-  disclaimer?: FeatureVisibility | DisclaimerConfig;
-  userProfile?: boolean | UserProfileConfig;
-  feedback?: FeatureVisibility | FeedbackConfig;
-  rating?: FeatureVisibility | RatingConfig;
-  faqs?: FeatureVisibility | FAQConfig;
-  cloudSync?: FeatureVisibility | CloudSyncConfig;
-  subscription?: FeatureVisibility | SubscriptionConfig;
-  wallet?: FeatureVisibility | WalletConfig;
-  emptyStateText?: string;
-}
-```
-
-#### Usage Examples
-
-**Simple Configuration:**
-
-```typescript
-const config: SettingsConfig = {
-  appearance: true,
-  language: true,
-  notifications: 'auto',
-  about: false,
-};
-```
-
-**Advanced Configuration:**
-
-```typescript
-const config: SettingsConfig = {
-  appearance: {
-    enabled: true,
-    route: 'CustomAppearance',
-    showThemeSection: true,
-    showColorsSection: true,
-  },
-  language: {
-    enabled: 'auto',
-    route: 'LanguageSelection',
-    showFlags: true,
-  },
-  subscription: {
-    enabled: true,
-    title: 'Upgrade to Pro',
-    onPress: () => navigation.navigate('Upgrade'),
-  },
-};
-```
-
-### FeatureVisibility
-
-Feature enablement type:
-
-```typescript
-type FeatureVisibility = boolean | 'auto';
-```
-
-- `true`: Always show feature
-- `false`: Never show feature
-- `'auto'`: Automatically detect based on navigation
-
-### NormalizedConfig
-
-Normalized configuration with consistent structure:
-
-```typescript
-interface NormalizedConfig {
-  appearance: {
-    enabled: boolean;
-    config?: AppearanceConfig;
-  };
-  language: {
-    enabled: boolean;
-    config?: LanguageConfig;
-  };
-  notifications: {
-    enabled: boolean;
-    config?: NotificationsConfig;
-  };
-  // ... other features
-}
-```
-
-### CustomSettingsSection
-
-Type for custom settings sections:
-
-```typescript
-interface CustomSettingsSection {
-  id?: string;
-  title: string;
-  order?: number;
-  content?: ReactNode;
-  items?: CustomSettingsItem[];
-}
-```
-
-### CustomSettingsItem
-
-Type for custom settings items:
-
-```typescript
-interface CustomSettingsItem {
-  id?: string;
-  title: string;
-  subtitle?: string;
-  icon: IconName;
-  onPress?: () => void;
-  rightIcon?: IconName;
-  iconBgColor?: string;
-  iconColor?: string;
-}
-```
-
-## Content Configuration Types
-
-### AppearanceConfig
-
-```typescript
-interface AppearanceConfig {
-  enabled?: FeatureVisibility;
-  route?: string;
-  showThemeSection?: boolean;
-  showColorsSection?: boolean;
-  showPreviewSection?: boolean;
-}
-```
-
-### LanguageConfig
-
-```typescript
-interface LanguageConfig {
-  enabled?: FeatureVisibility;
-  route?: string;
-  showFlags?: boolean;
-}
-```
-
-### NotificationsConfig
+## Purpose
 
-```typescript
-interface NotificationsConfig {
-  enabled?: FeatureVisibility;
-  route?: string;
-  showQuietHours?: boolean;
-  showCategories?: boolean;
-}
-```
-
-### AboutConfig
-
-```typescript
-interface AboutConfig {
-  enabled?: FeatureVisibility;
-  route?: string;
-  appName?: string;
-  version?: string;
-  buildNumber?: string;
-  developer?: string;
-  contactEmail?: string;
-  websiteUrl?: string;
-  websiteDisplay?: string;
-  moreAppsUrl?: string;
-}
-```
-
-### LegalConfig
-
-```typescript
-interface LegalConfig {
-  enabled?: FeatureVisibility;
-  route?: string;
-  showPrivacy?: boolean;
-  showTerms?: boolean;
-  showEula?: boolean;
-  privacyPolicyUrl?: string;
-  termsOfServiceUrl?: string;
-  eulaUrl?: string;
-}
-```
-
-### DisclaimerConfig
-
-```typescript
-interface DisclaimerConfig {
-  enabled?: FeatureVisibility;
-  route?: string;
-  title?: string;
-  message?: string;
-  shortMessage?: string;
-}
-```
-
-## User Feature Types
-
-### UserProfileConfig
-
-```typescript
-interface UserProfileConfig {
-  displayName?: string;
-  userId?: string;
-  isAnonymous?: boolean;
-  avatarUrl?: string;
-  accountSettingsRoute?: string;
-  onPress?: () => void;
-  anonymousDisplayName?: string;
-  avatarServiceUrl?: string;
-}
-```
-
-### FeedbackConfig
-
-```typescript
-interface FeedbackConfig {
-  enabled?: FeatureVisibility;
-  title?: string;
-  description?: string;
-  feedbackTypes?: FeedbackType[];
-}
-```
-
-### RatingConfig
-
-```typescript
-interface RatingConfig {
-  enabled?: FeatureVisibility;
-  title?: string;
-  description?: string;
-  storeUrl?: string;
-}
-```
-
-### FAQConfig
-
-```typescript
-interface FAQConfig {
-  enabled?: FeatureVisibility;
-  title?: string;
-  description?: string;
-  categories?: FAQCategory[];
-}
-```
-
-### SubscriptionConfig
-
-```typescript
-interface SubscriptionConfig {
-  enabled?: FeatureVisibility;
-  title?: string;
-  description?: string;
-  icon?: string;
-  onPress?: () => void;
-  sectionTitle?: string;
-}
-```
-
-### WalletConfig
-
-```typescript
-interface WalletConfig {
-  enabled?: FeatureVisibility;
-  title?: string;
-  description?: string;
-  icon?: string;
-  route?: string;
-  sectionTitle?: string;
-}
-```
-
-### CloudSyncConfig
-
-```typescript
-interface CloudSyncConfig {
-  enabled?: FeatureVisibility;
-  title?: string;
-  description?: string;
-}
-```
-
-## Base Types
-
-### BaseTypes.ts
-
-```typescript
-type FeatureVisibility = boolean | 'auto';
-```
-
-### ContentConfig.ts
-
-```typescript
-export interface AppearanceConfig { ... }
-export interface LanguageConfig { ... }
-export interface NotificationsConfig { ... }
-export interface AboutConfig { ... }
-export interface LegalConfig { ... }
-export interface DisclaimerConfig { ... }
-```
-
-### UserFeatureConfig.ts
+TypeScript type definitions for settings screen configuration, components, and utilities.
 
-```typescript
-export interface UserProfileConfig { ... }
-export interface FeedbackConfig { ... }
-export interface RatingConfig { ... }
-export interface FAQConfig { ... }
-export interface CloudSyncConfig { ... }
-export interface SubscriptionConfig { ... }
-export interface WalletConfig { ... }
-```
+## File Paths
 
-## Type Guards
+- **Base Types**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/screens/types/BaseTypes.ts`
+- **Content Config**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/screens/types/ContentConfig.ts`
+- **User Features**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/screens/types/UserFeatureConfig.ts`
+- **Custom Sections**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/screens/types/CustomSection.ts`
+- **Settings Config**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/screens/types/SettingsConfig.ts`
+- **Index**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/screens/types/index.ts`
 
-### Checking Config Type
+## Strategy
 
-```typescript
-function isAppearanceConfig(
-  value: FeatureVisibility | AppearanceConfig
-): value is AppearanceConfig {
-  return typeof value === 'object' && value !== null;
-}
+1. **Type Safety**: Provides comprehensive TypeScript types for all settings functionality
+2. **Config Validation**: Ensures configuration objects are properly typed
+3. **Modular Organization**: Separates types by feature domain
+4. **Reusability**: Exports types for use across the application
+5. **Documentation**: Types serve as inline documentation
 
-// Usage
-if (isAppearanceConfig(config.appearance)) {
-  console.log(config.appearance.route); // TypeScript knows this exists
-}
-```
+## Restrictions (Forbidden)
 
-### Checking Feature Enabled
+### DO NOT
+- ❌ DO NOT use `any` type for configuration objects
+- ❌ DO NOT bypass type checking with type assertions
+- ❌ DO NOT create duplicate type definitions
 
-```typescript
-function isFeatureEnabled(
-  value: FeatureVisibility | any
-): boolean {
-  if (value === 'auto') return true; // Will be detected
-  if (typeof value === 'boolean') return value;
-  if (value?.enabled === 'auto') return true;
-  return value?.enabled === true;
-}
+### NEVER
+- ❌ NEVER use config objects without proper typing
+- ❌ NEVER assume optional properties exist without checking
+- ❌ NEVER mix config types (e.g., pass AppearanceConfig where LanguageConfig expected)
 
-// Usage
-if (isFeatureEnabled(config.appearance)) {
-  // Feature is enabled
-}
-```
+### AVOID
+- ❌ AVOID creating overly complex nested types
+- ❌ AVOID circular type dependencies
+- ❌ AVOID type definitions that don't match actual usage
 
-## Type Exports
+## Rules (Mandatory)
 
-All types are exported from:
+### ALWAYS
+- ✅ ALWAYS use proper TypeScript types for config objects
+- ✅ ALWAYS use type guards for checking config object types
+- ✅ MUST provide type exports for public API
+- ✅ MUST keep types in sync with actual usage
 
-```typescript
-// types/index.ts
-export * from './BaseTypes';
-export * from './ContentConfig';
-export * from './UserFeatureConfig';
-export * from './CustomSection';
-export * from './SettingsConfig';
-```
+### MUST
+- ✅ MUST use FeatureVisibility type for feature enablement
+- ✅ MUST validate config at runtime when needed
+- ✅ MUST use proper generics for reusable types
 
-## Usage Examples
+### SHOULD
+- ✅ SHOULD use type aliases for common patterns
+- ✅ SHOULD document complex types with comments
+- ✅ SHOULD keep types simple and focused
 
-### Type-Safe Config
+## AI Agent Guidelines
 
-```typescript
-import type { SettingsConfig, AppearanceConfig } from '@umituz/react-native-settings';
+1. **File Reference**: When modifying types, refer to files in `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/screens/types/`
+2. **Type Safety**: Always use types from this module, never create inline types
+3. **FeatureVisibility**: Understand the three values: true (enabled), false (disabled), 'auto' (detect)
+4. **Type Guards**: Use type guards to safely check config object types
+5. **Exports**: Import types from the main index file for consistency
 
-const config: SettingsConfig = {
-  appearance: {
-    enabled: true,
-    route: 'CustomAppearance',
-    showThemeSection: true,
-    showColorsSection: false,
-  },
-};
-```
+## Type Reference
 
-### Custom Section Type
+### Core Types
 
-```typescript
-import type { CustomSettingsSection } from '@umituz/react-native-settings';
+**FeatureVisibility**: `boolean | 'auto'`
+- true: Always show feature
+- false: Never show feature
+- 'auto': Automatically detect based on navigation
 
-const customSection: CustomSettingsSection = {
-  id: 'custom',
-  title: 'CUSTOM SECTION',
-  order: 1,
-  items: [
-    {
-      id: 'item1',
-      title: 'Custom Item',
-      icon: 'settings-outline',
-      onPress: () => console.log('Pressed'),
-    },
-  ],
-};
-```
+**SettingsConfig**: Main configuration interface with all features
+- Supports boolean, 'auto', or object config for each feature
 
-### Type Inference
+**NormalizedConfig**: Normalized structure with enabled flags and config objects
+- Consistent format for all features
+- Used internally after normalization
 
-```typescript
-import { normalizeSettingsConfig } from '@umituz/react-native-settings';
-import type { NormalizedConfig } from '@umituz/react-native-settings';
+### Feature Config Types
 
-const normalized: NormalizedConfig = normalizeSettingsConfig(config);
-```
+**AppearanceConfig**: Appearance settings configuration
+**LanguageConfig**: Language selection configuration
+**NotificationsConfig**: Notification settings configuration
+**AboutConfig**: About screen configuration
+**LegalConfig**: Legal screen configuration
 
-## Best Practices
+### User Feature Types
 
-1. **Type Safety**: Always use proper TypeScript types
-2. **Type Guards**: Use type guards for config objects
-3. **Defaults**: Provide sensible defaults for all config
-4. **Validation**: Validate config at runtime
-5. **Documentation**: Document custom config objects
-6. **Type Exports**: Use centralized type exports
-7. **Generic Types**: Leverage generics for reusability
+**UserProfileConfig**: User profile display configuration
+**FeedbackConfig**: Feedback functionality configuration
+**RatingConfig**: App rating prompt configuration
+**FAQConfig**: FAQ section configuration
+**SubscriptionConfig**: Subscription/upgrade configuration
+**WalletConfig**: Wallet settings configuration
 
-## Related
+### Custom Types
 
-- **normalizeConfig**: Config normalization utilities
-- **useFeatureDetection**: Feature detection hook
-- **SettingsScreen**: Main screen component
+**CustomSettingsSection**: Custom section definition
+**CustomSettingsItem**: Custom item within a section
 
-## License
+## Related Components
 
-MIT
+- **normalizeSettingsConfig**: Uses these types for normalization
+- **SettingsScreen**: Uses these types for props
+- **useFeatureDetection**: Uses these types for feature flags