@umituz/react-native-settings 4.20.58 → 4.20.60

package/src/domains/appearance/infrastructure/services/README.md

@@ -2,437 +2,129 @@
 
 Service layer for appearance domain including system theme detection, validation, and appearance management.
 
-## Services
+## Purpose
 
-### AppearanceService
-
-Main service for managing appearance settings including theme mode, custom colors, and system theme detection.
-
-```typescript
-import { AppearanceService } from '@umituz/react-native-settings';
-
-const appearanceService = new AppearanceService();
-
-// Get current theme mode
-const themeMode = await appearanceService.getThemeMode();
-
-// Set theme mode
-await appearanceService.setThemeMode('dark');
-
-// Get custom colors
-const colors = await appearanceService.getCustomColors();
+Provides business logic services for managing appearance settings including theme mode, custom colors, and system theme detection. Services encapsulate complex operations and provide a clean API for the domain.
 
-// Set custom colors
-await appearanceService.setCustomColors({ primary: '#FF5722' });
+## File Paths
 
-// Reset to defaults
-await appearanceService.resetColors();
 ```
-
-#### Methods
-
-**getThemeMode(): Promise<'light' | 'dark' | 'auto'>**
-
-Gets the current theme mode setting.
-
-```typescript
-const themeMode = await appearanceService.getThemeMode();
-console.log(themeMode); // 'light' | 'dark' | 'auto'
+src/domains/appearance/infrastructure/services/
+├── AppearanceService.ts               # Main appearance management
+├── SystemThemeDetectionService.ts     # System theme detection
+└── ValidationService.ts               # Color/theme validation
 ```
 
-**setThemeMode(mode: 'light' | 'dark' | 'auto'): Promise<void>**
+## Strategy
 
-Sets the theme mode setting.
+1. **Service Encapsulation**: Encapsulate complex appearance logic in service classes
+2. **System Integration**: Detect and respond to system theme changes
+3. **Validation First**: Validate all appearance changes before applying
+4. **Event-Driven**: Use event listeners for system theme changes
+5. **Type Safety**: Provide strongly typed service interfaces
 
-```typescript
-await appearanceService.setThemeMode('dark');
-```
+## Restrictions
 
-**getCustomColors(): Promise<ColorPalette | undefined>**
+### DO NOT
 
-Gets the custom color palette if set.
+- ❌ DO NOT include UI components or React hooks in services
+- ❌ DO NOT directly access storage; use repositories
+- ❌ DO NOT mix validation logic with business logic
+- ❌ DO NOT create circular dependencies between services
+- ❌ DO NOT swallow validation errors
 
-```typescript
-const colors = await appearanceService.getCustomColors();
-if (colors) {
-  console.log(colors.primary);
-}
-```
+### NEVER
 
-**setCustomColors(colors: ColorPalette): Promise<void>**
+- ❌ NEVER apply invalid color values
+- ❌ NEVER assume system theme is available
+- ❌ EVER bypass validation for any reason
+- ❌ EVER store raw hex values without validation
 
-Sets the custom color palette.
+### AVOID
 
-```typescript
-await appearanceService.setCustomColors({
-  primary: '#FF5722',
-  secondary: '#2196F3',
-  accent: '#FFC107',
-  background: '#FFFFFF',
-  surface: '#F5F5F5',
-});
-```
+- ❌ AVOID creating god services that do too much
+- ❌ AVOID tight coupling between services
+- ❌ AVOID synchronous operations for appearance changes
+- ❌ AVOID ignoring system theme change events
 
-**resetColors(): Promise<void>**
+## Rules
 
-Resets colors to default theme.
+### ALWAYS
 
-```typescript
-await appearanceService.resetColors();
-```
+- ✅ ALWAYS validate theme modes before applying
+- ✅ ALWAYS validate hex color format before applying
+- ✅ ALWAYS handle system theme unsubscription
+- ✅ ALWAYS return typed results from service methods
+- ✅ ALWAYS handle service errors gracefully
 
-### SystemThemeDetectionService
+### MUST
 
-Service for detecting and monitoring system theme changes.
+- ✅ MUST validate all inputs before processing
+- ✅ MUST provide clear error messages for validation failures
+- ✅ MUST clean up event listeners on cleanup
+- ✅ MUST respect user preferences over system defaults
 
-```typescript
-import { SystemThemeDetectionService } from '@umituz/react-native-settings';
+### SHOULD
 
-const detectionService = new SystemThemeDetectionService();
+- ✅ SHOULD provide reactive interfaces for theme changes
+- ✅ SHOULD cache theme detection results
+- ✅ SHOULD offer batch operations for multiple changes
+- ✅ SHOULD log important service operations
 
-// Get current system theme
-const systemTheme = detectionService.getSystemTheme();
-console.log(systemTheme); // 'light' | 'dark' | null
+## AI Agent Guidelines
 
-// Listen for system theme changes
-const unsubscribe = detectionService.listen((theme) => {
-  console.log('System theme changed to:', theme);
-});
+1. **When creating services**: Keep them focused and single-purpose
+2. **When adding validation**: Provide clear, actionable error messages
+3. **When detecting system theme**: Use native APIs with fallbacks
+4. **When managing colors**: Validate hex format (#RRGGBB) before applying
+5. **When handling errors**: Transform technical errors into user-friendly messages
 
-// Stop listening
-unsubscribe();
-```
+## Services Reference
 
-#### Methods
+### AppearanceService
 
-**getSystemTheme(): 'light' | 'dark' | null**
+Main service for managing appearance settings including theme mode, custom colors, and system theme detection.
 
-Gets the current system theme preference.
+**Location**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/appearance/infrastructure/services/AppearanceService.ts`
 
-```typescript
-const theme = detectionService.getSystemTheme();
-if (theme === 'dark') {
-  console.log('System is in dark mode');
-}
-```
+**Methods**:
+- `getThemeMode(): Promise<'light' | 'dark' | 'auto'>` - Get current theme mode
+- `setThemeMode(mode: 'light' | 'dark' | 'auto'): Promise<void>` - Set theme mode
+- `getCustomColors(): Promise<ColorPalette | undefined>` - Get custom colors
+- `setCustomColors(colors: ColorPalette): Promise<void>` - Set custom colors
+- `resetColors(): Promise<void>` - Reset to default colors
 
-**listen(callback: (theme: 'light' | 'dark') => void): () => void**
+### SystemThemeDetectionService
 
-Listens for system theme changes.
+Service for detecting and monitoring system theme changes.
 
-```typescript
-const unsubscribe = detectionService.listen((theme) => {
-  console.log('Theme changed to:', theme);
-  // Update app theme accordingly
-});
+**Location**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/appearance/infrastructure/services/SystemThemeDetectionService.ts`
 
-// Cleanup on unmount
-useEffect(() => {
-  return () => unsubscribe();
-}, []);
-```
+**Methods**:
+- `getSystemTheme(): 'light' | 'dark' | null` - Get current system theme
+- `listen(callback: (theme: 'light' | 'dark') => void): () => void` - Listen for changes
 
 ### ValidationService
 
 Service for validating appearance settings.
 
-```typescript
-import { ValidationService } from '@umituz/react-native-settings';
-
-const validationService = new ValidationService();
-
-// Validate theme mode
-const themeValid = validationService.validateThemeMode('dark');
-console.log(themeValid); // true
-
-const themeInvalid = validationService.validateThemeMode('invalid');
-console.log(themeInvalid); // false
+**Location**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/appearance/infrastructure/services/ValidationService.ts`
 
-// Validate color hex
-const colorValid = validationService.validateColor('#FF5722');
-console.log(colorValid); // true
-
-const colorInvalid = validationService.validateColor('invalid');
-console.log(colorInvalid); // false
-
-// Validate color palette
-const paletteValid = validationService.validateColorPalette({
-  primary: '#FF5722',
-  secondary: '#2196F3',
-});
-console.log(paletteValid); // true
-```
+**Methods**:
+- `validateThemeMode(mode: string): boolean` - Validate theme mode
+- `validateColor(color: string): boolean` - Validate hex color
+- `validateColorPalette(palette: ColorPalette): boolean` - Validate complete palette
 
-#### Methods
+## Color Palette Structure
 
-**validateThemeMode(mode: string): boolean**
-
-Validates if the provided mode is a valid theme mode.
-
-```typescript
-if (validationService.validateThemeMode(themeMode)) {
-  await appearanceService.setThemeMode(themeMode);
-} else {
-  console.error('Invalid theme mode');
-}
-```
-
-**validateColor(color: string): boolean**
-
-Validates if the provided string is a valid hex color.
-
-```typescript
-if (validationService.validateColor('#FF5722')) {
-  // Color is valid
-}
-```
-
-**validateColorPalette(palette: ColorPalette): boolean**
-
-Validates a complete color palette.
-
-```typescript
-const palette = {
-  primary: '#FF5722',
-  secondary: '#2196F3',
-  accent: '#FFC107',
-  background: '#FFFFFF',
-  surface: '#F5F5F5',
-};
-
-if (validationService.validateColorPalette(palette)) {
-  await appearanceService.setCustomColors(palette);
-}
-```
-
-## Usage Examples
-
-### Auto Theme with System Detection
-
-```tsx
-function useAutoTheme() {
-  const [theme, setTheme] = useState<'light' | 'dark'>('light');
-  const { themeMode } = useAppearance();
-
-  useEffect(() => {
-    if (themeMode === 'auto') {
-      // Use system theme
-      const systemTheme = SystemThemeDetectionService.getSystemTheme();
-      if (systemTheme) {
-        setTheme(systemTheme);
-      }
-
-      // Listen for changes
-      const unsubscribe = SystemThemeDetectionService.listen((newTheme) => {
-        setTheme(newTheme);
-      });
-
-      return unsubscribe;
-    } else {
-      // Use explicit theme
-      setTheme(themeMode === 'dark' ? 'dark' : 'light');
-    }
-  }, [themeMode]);
-
-  return theme;
-}
-```
-
-### Theme Persistence
-
-```tsx
-class ThemePersistence {
-  private service: AppearanceService;
-
-  constructor() {
-    this.service = new AppearanceService();
-  }
-
-  async loadTheme(): Promise<'light' | 'dark' | 'auto'> {
-    const mode = await this.service.getThemeMode();
-    return mode;
-  }
-
-  async saveTheme(mode: 'light' | 'dark' | 'auto'): Promise<void> {
-    await this.service.setThemeMode(mode);
-  }
-
-  async loadColors(): Promise<ColorPalette | undefined> {
-    return await this.service.getCustomColors();
-  }
-
-  async saveColors(colors: ColorPalette): Promise<void> {
-    if (ValidationService.validateColorPalette(colors)) {
-      await this.service.setCustomColors(colors);
-    } else {
-      throw new Error('Invalid color palette');
-    }
-  }
-}
-```
-
-### Color Validation
-
-```tsx
-function ColorInput({ value, onChange }) {
-  const validationService = new ValidationService();
-  const [error, setError] = useState<string | null>(null);
-
-  const handleChange = (color: string) => {
-    if (validationService.validateColor(color)) {
-      setError(null);
-      onChange(color);
-    } else {
-      setError('Invalid color format. Use hex format: #RRGGBB');
-    }
-  };
-
-  return (
-    <View>
-      <TextInput
-        value={value}
-        onChangeText={handleChange}
-        placeholder="#FF5722"
-      />
-      {error && <Text style={styles.error}>{error}</Text>}
-    </View>
-  );
-}
-```
-
-### Theme Switcher with Validation
-
-```tsx
-function ThemeSwitcher() {
-  const { themeMode, setThemeMode } = useAppearance();
-  const validationService = new ValidationService();
-
-  const handleThemeChange = async (mode: string) => {
-    if (validationService.validateThemeMode(mode)) {
-      await setThemeMode(mode as 'light' | 'dark' | 'auto');
-    } else {
-      Alert.alert('Error', 'Invalid theme mode');
-    }
-  };
-
-  return (
-    <View>
-      <Button
-        onPress={() => handleThemeChange('light')}
-        title="Light Mode"
-      />
-      <Button
-        onPress={() => handleThemeChange('dark')}
-        title="Dark Mode"
-      />
-      <Button
-        onPress={() => handleThemeChange('auto')}
-        title="Auto Mode"
-      />
-    </View>
-  );
-}
-```
-
-### Complete Appearance Manager
-
-```tsx
-class AppearanceManager {
-  private appearanceService: AppearanceService;
-  private detectionService: SystemThemeDetectionService;
-  private validationService: ValidationService;
-
-  constructor() {
-    this.appearanceService = new AppearanceService();
-    this.detectionService = new SystemThemeDetectionService();
-    this.validationService = new ValidationService();
-  }
-
-  async initialize(): Promise<void> {
-    const mode = await this.appearanceService.getThemeMode();
-    return mode;
-  }
-
-  async setTheme(mode: 'light' | 'dark' | 'auto'): Promise<void> {
-    if (!this.validationService.validateThemeMode(mode)) {
-      throw new Error('Invalid theme mode');
-    }
-
-    await this.appearanceService.setThemeMode(mode);
-  }
-
-  getEffectiveTheme(): 'light' | 'dark' {
-    const mode = this.appearanceService.getThemeMode();
-    if (mode === 'auto') {
-      return this.detectionService.getSystemTheme() || 'light';
-    }
-    return mode;
-  }
-
-  listenToThemeChanges(callback: (theme: 'light' | 'dark') => void): () => void {
-    return this.detectionService.listen(callback);
-  }
-
-  async setCustomColors(colors: ColorPalette): Promise<void> {
-    if (!this.validationService.validateColorPalette(colors)) {
-      throw new Error('Invalid color palette');
-    }
-
-    await this.appearanceService.setCustomColors(colors);
-  }
-
-  async reset(): Promise<void> {
-    await this.appearanceService.resetColors();
-  }
-}
-```
-
-## Color Palette
-
-```typescript
-interface ColorPalette {
-  primary: string;      // #FF5722
-  secondary: string;    // #2196F3
-  accent: string;       // #FFC107
-  background: string;   // #FFFFFF
-  surface: string;      // #F5F5F5
-  error: string;        // #F44336
-  success: string;      // #4CAF50
-  warning: string;      // #FF9800
-}
-```
-
-## Default Palettes
-
-### Light Theme
-
-```typescript
-const lightColors: ColorPalette = {
-  primary: '#FF5722',
-  secondary: '#2196F3',
-  accent: '#FFC107',
-  background: '#FFFFFF',
-  surface: '#F5F5F5',
-  error: '#F44336',
-  success: '#4CAF50',
-  warning: '#FF9800',
-};
-```
-
-### Dark Theme
-
-```typescript
-const darkColors: ColorPalette = {
-  primary: '#FF5722',
-  secondary: '#2196F3',
-  accent: '#FFC107',
-  background: '#121212',
-  surface: '#1E1E1E',
-  error: '#EF5350',
-  success: '#66BB6A',
-  warning: '#FFA726',
-};
-```
+**Primary**: Main brand color (#FF5722)
+**Secondary**: Secondary brand color (#2196F3)
+**Accent**: Highlight color (#FFC107)
+**Background**: Background color (#FFFFFF)
+**Surface**: Surface/card color (#F5F5F5)
+**Error**: Error state color (#F44336)
+**Success**: Success state color (#4CAF50)
+**Warning**: Warning state color (#FF9800)
 
 ## Best Practices
 
@@ -444,12 +136,6 @@ const darkColors: ColorPalette = {
 6. **Persistence**: Save theme changes immediately
 7. **Performance**: Cache theme detection results
 
-## Related
-
-- **Appearance Hooks**: React hooks for appearance
-- **Appearance Components**: UI components for appearance
-- **Appearance Repository**: Data persistence layer
-
 ## License
 
 MIT