@umituz/react-native-settings 4.20.58 → 4.20.59

package/src/domains/appearance/hooks/README.md

@@ -2,345 +2,144 @@
 
 Custom hooks for managing appearance settings including theme mode and custom colors.
 
-## Hooks
+## Purpose
 
-### useAppearance
-
-Hook for accessing current appearance settings and theme mode.
-
-```tsx
-import { useAppearance } from '@umituz/react-native-settings';
-
-function AppearanceScreen() {
-  const { themeMode, customColors, isLoading } = useAppearance();
-
-  return (
-    <View>
-      <Text>Current theme: {themeMode}</Text>
-      {customColors && <Text>Custom colors enabled</Text>}
-    </View>
-  );
-}
-```
-
-#### Returns
-
-```typescript
-interface UseAppearanceResult {
-  themeMode: 'light' | 'dark' | 'auto';   // Current theme mode
-  customColors?: ColorPalette;             // Custom color palette
-  isLoading: boolean;                      // Loading state
-  error?: Error;                           // Error object
-}
-```
-
-#### Examples
-
-**Basic Usage:**
-
-```tsx
-function ThemeDisplay() {
-  const { themeMode } = useAppearance();
-
-  return (
-    <Text>Current theme: {themeMode}</Text>
-  );
-}
-```
-
-**With Loading State:**
-
-```tsx
-function ThemeSelector() {
-  const { themeMode, isLoading } = useAppearance();
-
-  if (isLoading) {
-    return <ActivityIndicator />;
-  }
-
-  return (
-    <Picker selectedValue={themeMode}>
-      <Picker.Item label="Light" value="light" />
-      <Picker.Item label="Dark" value="dark" />
-      <Picker.Item label="Auto" value="auto" />
-    </Picker>
-  );
-}
-```
-
-**With Custom Colors:**
-
-```tsx
-function ColorDisplay() {
-  const { customColors } = useAppearance();
-
-  return (
-    <View>
-      <View style={{ backgroundColor: customColors?.primary }} />
-      <View style={{ backgroundColor: customColors?.secondary }} />
-      <View style={{ backgroundColor: customColors?.accent }} />
-    </View>
-  );
-}
-```
-
-### useAppearanceActions
-
-Hook for accessing appearance action functions to update theme and colors.
+Provides React hooks for accessing and manipulating appearance settings. These hooks bridge the UI layer with the appearance domain's business logic, offering a clean interface for theme management and color customization.
 
-```tsx
-import { useAppearanceActions } from '@umituz/react-native-settings';
+## File Paths
 
-function AppearanceControls() {
-  const { setThemeMode, setCustomColors, resetColors } = useAppearanceActions();
-
-  const handleThemeChange = (theme: 'light' | 'dark') => {
-    setThemeMode(theme);
-  };
-
-  const handleSetColors = (colors: ColorPalette) => {
-    setCustomColors(colors);
-  };
-
-  const handleReset = () => {
-    resetColors();
-  };
-
-  return (
-    <View>
-      <Button onPress={() => handleThemeChange('dark')} title="Dark Mode" />
-      <Button onPress={() => handleSetColors(newColors)} title="Set Colors" />
-      <Button onPress={handleReset} title="Reset Colors" />
-    </View>
-  );
-}
 ```
-
-#### Returns
-
-```typescript
-interface UseAppearanceActionsResult {
-  setThemeMode: (themeMode: 'light' | 'dark' | 'auto') => void;
-  setCustomColors: (colors: ColorPalette) => void;
-  resetColors: () => void;
-  isUpdating: boolean;
-}
+src/domains/appearance/hooks/
+├── useAppearance.ts             # Access appearance settings
+└── useAppearanceActions.ts      # Modify appearance settings
 ```
 
-#### Actions
+## Strategy
 
-**setThemeMode:**
+1. **Separation of Concerns**: Split read operations (useAppearance) from write operations (useAppearanceActions)
+2. **Automatic Persistence**: All changes are automatically persisted without manual save operations
+3. **Type Safety**: Strongly typed theme modes and color palettes
+4. **System Integration**: Respect system theme preferences when in auto mode
+5. **Reactive Updates**: Automatically trigger re-renders when appearance changes
 
-Sets the theme mode.
+## Restrictions
 
-```tsx
-const { setThemeMode } = useAppearanceActions();
+### DO NOT
 
-// Set to dark mode
-setThemeMode('dark');
+- ❌ DO NOT mix appearance hooks with direct settings manipulation
+- ❌ DO NOT bypass validation when setting custom colors
+- ❌ DO NOT assume theme mode is always the same as effective theme
+- ❌ DO NOT manually manage persistence; hooks handle this automatically
+- ❌ DO NOT create circular dependencies between appearance hooks
 
-// Set to light mode
-setThemeMode('light');
+### NEVER
 
-// Set to auto (system preference)
-setThemeMode('auto');
-```
-
-**setCustomColors:**
-
-Sets custom color palette.
-
-```tsx
-const { setCustomColors } = useAppearanceActions();
+- ❌ NEVER call useAppearanceActions outside React components
+- ❌ NEVER ignore loading states during appearance operations
+- ❌ EVER hardcode color values; use the hooks instead
+- ❌ EVER mutate theme state directly; use action hooks
 
-const colors = {
-  primary: '#FF5722',
-  secondary: '#2196F3',
-  accent: '#FFC107',
-  background: '#FFFFFF',
-  surface: '#F5F5F5',
-};
+### AVOID
 
-setCustomColors(colors);
-```
-
-**resetColors:**
+- ❌ AVOID frequent theme changes without debouncing
+- ❌ AVOID creating custom appearance logic outside these hooks
+- ❌ AVOID inconsistent theme application across components
+- ❌ AVOID ignoring system theme preferences in auto mode
 
-Resets to default colors.
+## Rules
 
-```tsx
-const { resetColors } = useAppearanceActions();
+### ALWAYS
 
-resetColors();
-```
+- ✅ ALWAYS use useAppearance for reading appearance state
+- ✅ ALWAYS use useAppearanceActions for modifying appearance
+- ✅ ALWAYS validate color values before setting custom colors
+- ✅ ALWAYS handle loading states during theme operations
+- ✅ ALWAYS respect system theme when mode is 'auto'
 
-## Complete Example
+### MUST
 
-### Theme Switcher
+- ✅ MUST apply theme changes consistently across the app
+- ✅ MUST provide visual feedback for theme changes
+- ✅ MUST handle errors in color validation gracefully
+- ✅ MUST persist changes immediately
 
-```tsx
-function ThemeSwitcher() {
-  const { themeMode } = useAppearance();
-  const { setThemeMode } = useAppearanceActions();
+### SHOULD
 
-  return (
-    <View>
-      <Text>Current Theme: {themeMode}</Text>
+- ✅ SHOULD use useMemo for expensive theme computations
+- ✅ SHOULD provide smooth transitions between theme changes
+- ✅ SHOULD offer reset functionality for custom colors
+- ✅ SHOULD show live preview of appearance changes
 
-      <TouchableOpacity onPress={() => setThemeMode('light')}>
-        <Text>Light Mode</Text>
-      </TouchableOpacity>
+## AI Agent Guidelines
 
-      <TouchableOpacity onPress={() => setThemeMode('dark')}>
-        <Text>Dark Mode</Text>
-      </TouchableOpacity>
+1. **When creating custom appearance hooks**: Compose existing hooks rather than creating new ones
+2. **When adding new theme modes**: Extend the theme mode type and update all switch statements
+3. **When customizing colors**: Always validate hex format before applying
+4. **When integrating system theme**: Use useColorScheme for detecting system preferences
+5. **When debugging appearance**: Use React DevTools to inspect hook state and dependencies
 
-      <TouchableOpacity onPress={() => setThemeMode('auto')}>
-        <Text>Auto (System)</Text>
-      </TouchableOpacity>
-    </View>
-  );
-}
-```
+## Hooks Reference
 
-### Color Customizer
-
-```tsx
-function ColorCustomizer() {
-  const { customColors } = useAppearance();
-  const { setCustomColors, resetColors } = useAppearanceActions();
-
-  const [colors, setColors] = useState(customColors || defaultColors);
-
-  const handleSave = () => {
-    setCustomColors(colors);
-  };
-
-  const handleReset = () => {
-    resetColors();
-    setColors(defaultColors);
-  };
-
-  return (
-    <View>
-      <ColorPicker
-        label="Primary Color"
-        value={colors.primary}
-        onChange={(color) => setColors({ ...colors, primary: color })}
-      />
-
-      <ColorPicker
-        label="Secondary Color"
-        value={colors.secondary}
-        onChange={(color) => setColors({ ...colors, secondary: color })}
-      />
-
-      <Button onPress={handleSave} title="Save Colors" />
-      <Button onPress={handleReset} title="Reset to Default" />
-    </View>
-  );
-}
-```
+### useAppearance
 
-### Theme Toggle Button
-
-```tsx
-function ThemeToggleButton() {
-  const { themeMode } = useAppearance();
-  const { setThemeMode } = useAppearanceActions();
-  const isDark = themeMode === 'dark';
-
-  const handleToggle = useCallback(() => {
-    setThemeMode(isDark ? 'light' : 'dark');
-  }, [isDark, setThemeMode]);
-
-  return (
-    <TouchableOpacity onPress={handleToggle}>
-      <Ionicons
-        name={isDark ? 'sunny-outline' : 'moon-outline'}
-        size={24}
-        color="black"
-      />
-    </TouchableOpacity>
-  );
-}
-```
+Hook for accessing current appearance settings and theme mode.
 
-### Live Preview
+**Location**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/appearance/hooks/useAppearance.ts`
 
-```tsx
-function AppearancePreview() {
-  const { themeMode, customColors } = useAppearance();
-  const { setThemeMode } = useAppearanceActions();
+**Returns**:
+- `themeMode: 'light' | 'dark' | 'auto'` - Current theme mode setting
+- `customColors?: ColorPalette` - Custom color palette if set
+- `isLoading: boolean` - Loading state indicator
+- `error?: Error` - Error object if operation failed
 
-  const effectiveTheme = useEffectiveTheme(themeMode);
+**Use Cases**:
+- Displaying current theme mode
+- Checking if custom colors are active
+- Rendering theme-aware UI components
 
-  return (
-    <View style={{ backgroundColor: effectiveTheme.background }}>
-      <Text style={{ color: effectiveTheme.text }}>
-        Theme Preview
-      </Text>
+### useAppearanceActions
 
-      <View style={{ backgroundColor: customColors?.primary }}>
-        <Text>Primary Color</Text>
-      </View>
+Hook for accessing appearance action functions to update theme and colors.
 
-      <TouchableOpacity onPress={() => setThemeMode('dark')}>
-        <Text>Switch to Dark</Text>
-      </TouchableOpacity>
-    </View>
-  );
-}
+**Location**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/appearance/hooks/useAppearanceActions.ts`
 
-function useEffectiveTheme(themeMode: 'light' | 'dark' | 'auto') {
-  const systemTheme = useColorScheme();
-  const effectiveMode = themeMode === 'auto' ? systemTheme : themeMode;
+**Returns**:
+- `setThemeMode: (mode: 'light' | 'dark' | 'auto') => void` - Set theme mode
+- `setCustomColors: (colors: ColorPalette) => void` - Set custom colors
+- `resetColors: () => void` - Reset to default colors
+- `isUpdating: boolean` - Update in progress indicator
 
-  return effectiveMode === 'dark' ? darkTheme : lightTheme;
-}
-```
+**Use Cases**:
+- Theme switcher component
+- Custom color picker
+- Reset appearance to defaults
 
-## System Theme Detection
+## Theme Modes
 
-### Auto Theme
+### Light Mode
 
-```tsx
-function AutoThemeDetector() {
-  const { themeMode } = useAppearance();
-  const systemTheme = useColorScheme();
+Explicit light theme regardless of system preferences.
 
-  const effectiveTheme = useMemo(() => {
-    if (themeMode === 'auto') {
-      return systemTheme;
-    }
-    return themeMode;
-  }, [themeMode, systemTheme]);
+### Dark Mode
 
-  return (
-    <Text>
-      Theme Mode: {themeMode}
-      Effective Theme: {effectiveTheme}
-    </Text>
-  );
-}
-```
+Explicit dark theme regardless of system preferences.
 
-### Theme Provider
+### Auto Mode
 
-```tsx
-function AppearanceProvider({ children }) {
-  const { themeMode, customColors } = useAppearance();
+Automatically switches between light and dark based on system preferences.
 
-  const theme = useMemo(() => ({
-    mode: themeMode,
-    colors: customColors || defaultColors,
-  }), [themeMode, customColors]);
+## Color Palette Structure
 
-  return (
-    <ThemeContext.Provider value={theme}>
-      {children}
-    </ThemeContext.Provider>
-  );
+```typescript
+interface ColorPalette {
+  primary: string;      // Primary brand color
+  secondary: string;    // Secondary brand color
+  accent: string;       // Accent/highlight color
+  background: string;   // Background color
+  surface: string;      // Surface/card color
+  error: string;        // Error state color
+  success: string;      // Success state color
+  warning: string;      // Warning state color
 }
 ```
 
@@ -354,13 +153,6 @@ function AppearanceProvider({ children }) {
 6. **Preview**: Show live preview of changes
 7. **Performance**: Use useMemo for expensive calculations
 
-## Related
-
-- **AppearanceScreen**: Appearance screen component
-- **ThemeModeSection**: Theme mode section
-- **CustomColorsSection**: Custom colors section
-- **Appearance Store**: Zustand store for appearance state
-
 ## License
 
 MIT