@umituz/react-native-settings 4.20.57 → 4.20.59

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

package/src/domains/appearance/presentation/components/README.md

@@ -0,0 +1,99 @@
+# Appearance Components
+
+## Purpose
+
+Components for theme management and appearance customization including theme selection, color picking, and live preview. Enables users to personalize their app experience with comprehensive theming options.
+
+## File Paths
+
+- **AppearanceScreen**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/appearance/presentation/screens/AppearanceScreen.tsx`
+- **ThemeModeSection**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/appearance/presentation/components/ThemeModeSection.tsx`
+- **CustomColorsSection**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/appearance/presentation/components/CustomColorsSection.tsx`
+- **AppearancePreview**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/appearance/presentation/components/AppearancePreview.tsx`
+- **ThemeOption**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/appearance/presentation/components/ThemeOption.tsx`
+- **ColorPicker**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/appearance/presentation/components/ColorPicker.tsx`
+
+## Strategy
+
+1. **Live Preview Implementation**: Shows real-time preview of theme changes as users make selections, providing immediate feedback and building confidence before applying changes globally.
+
+2. **System Theme Respect**: Implements "auto" mode that automatically switches between light and dark themes based on system preferences, providing a seamless native experience.
+
+3. **Progressive Customization**: Offers simple theme mode selection (light/dark/auto) for casual users and advanced color palette customization for power users, accommodating different user needs.
+
+4. **Design System Integration**: Works seamlessly with design system tokens, allowing theme changes to propagate consistently across all components without manual style updates.
+
+5. **Reset Capability**: Provides easy reset to defaults option, allowing users to quickly revert customizations if they're unsatisfied with their changes.
+
+## Restrictions
+
+### ❌ DO NOT
+
+- Hardcode color values anywhere in the app
+- Ignore system theme preference in auto mode
+- Make theme changes without user action
+- Break design system token dependencies
+- Allow invalid color hex codes
+
+### ❌ NEVER
+
+- Remove the reset to defaults option
+- Force a theme that violates accessibility standards
+- Make color changes without proper validation
+- Bypass theme persistence
+- Use different theme scales across the app
+
+### ❌ AVOID
+
+- Too many preset themes (keep under 10)
+- Clashing color combinations
+- Overly complex color customization UI
+- Delayed theme application
+- Inconsistent theme transition animations
+
+## Rules
+
+### ✅ ALWAYS
+
+- Show theme preview before applying changes
+- Save theme changes immediately
+- Respect system theme in auto mode
+- Validate color hex codes before applying
+- Ensure sufficient color contrast for accessibility
+
+### ✅ MUST
+
+- Provide light, dark, and auto theme options
+- Support design system token integration
+- Include reset to defaults button
+- Test themes in different lighting conditions
+- Maintain consistent theme across app lifecycle
+
+### ✅ SHOULD
+
+- Offer preset color palettes for quick selection
+- Use smooth transitions for theme changes
+- Show color names or hex codes for clarity
+- Provide theme customization in dedicated screen
+- Consider accessibility when selecting default colors
+- Test with various color blindness types
+
+## AI Agent Guidelines
+
+1. **Theme Mode Implementation**: Always offer three options: Light, Dark, and Auto. In Auto mode, use useColorScheme or Appearance API to detect system preference and switch automatically. Show the active theme in preview so users understand what Auto means.
+
+2. **Color Customization Strategy**: Provide preset color palettes (Ocean, Sunset, Forest, etc.) for users who want quick customization. For advanced users, offer individual color pickers for primary, secondary, and accent colors. Always validate hex codes and show color preview.
+
+3. **Preview UX**: Position preview at the top of the appearance screen so users see changes immediately. Update preview in real-time as users select options. Show various UI elements in preview (cards, buttons, text) to demonstrate theme comprehensively.
+
+4. **Persistence and Reset**: Save theme preferences to AsyncStorage immediately on change. Use keys like "theme-mode" and "custom-colors". The reset button should clear custom colors and revert to default theme mode (usually Auto or Light).
+
+5. **Accessibility Testing**: Always test custom color themes for contrast ratios. Use tools to ensure text meets WCAG AA standards (4.5:1 for normal text, 3:1 for large text). Warn users if their custom colors don't meet accessibility standards, or prevent applying them.
+
+## Reference
+
+- **Main Screen**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/appearance/presentation/screens/AppearanceScreen.tsx`
+- **Theme Components**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/appearance/presentation/components/`
+- **Appearance Hooks**: Check for useAppearance and related hooks for state management
+- **Appearance Services**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/appearance/services/`
+- **Design System Tokens**: Refer to design system for color definitions and theming infrastructure