@umituz/react-native-settings 4.20.58 → 4.20.59

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

@@ -1,493 +1,99 @@
 # Appearance Components
 
-Components for theme management and appearance customization including theme selection, color picking, and live preview.
+## Purpose
 
-## Components
-
-### AppearanceScreen
-
-Main screen for managing appearance settings including theme mode and custom colors.
-
-```tsx
-import { AppearanceScreen } from '@umituz/react-native-settings';
+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.
 
-function AppearanceStack() {
-  return (
-    <Stack.Screen
-      name="Appearance"
-      component={AppearanceScreen}
-      options={{ title: 'Appearance' }}
-    />
-  );
-}
-```
-
-#### Features
-
-- Theme mode selection (light/dark/auto)
-- Custom color palette configuration
-- Live theme preview
-- Reset to defaults
-
-#### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `route` | `RouteProp` | **Required** | Route with optional config |
-| `navigation` | `NavigationProp` | **Required** | Navigation object |
-
-#### Route Params
-
-```typescript
-interface AppearanceScreenParams {
-  showThemeSection?: boolean;
-  showColorsSection?: boolean;
-  showPreviewSection?: boolean;
-}
-```
-
-### ThemeModeSection
-
-Section component for selecting theme mode (light, dark, or auto/system).
-
-```tsx
-import { ThemeModeSection } from '@umituz/react-native-settings';
-
-function ThemeSelector() {
-  const { themeMode, setThemeMode } = useAppearance();
-
-  return (
-    <ThemeModeSection
-      themeMode={themeMode}
-      onThemeModeChange={setThemeMode}
-    />
-  );
-}
-```
-
-#### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `themeMode` | `'light' \| 'dark' \| 'auto'` | **Required** | Current theme mode |
-| `onThemeModeChange` | `(mode: 'light' \| 'dark' \| 'auto') => void` | **Required** | Theme change handler |
-| `showPreview` | `boolean` | `true` | Show theme preview |
-| `title` | `string` | `'Theme'` | Section title |
-
-#### Example
-
-```tsx
-<ThemeModeSection
-  themeMode="dark"
-  onThemeModeChange={(mode) => {
-    console.log('Theme changed to:', mode);
-    setThemeMode(mode);
-  }}
-  showPreview={true}
-  title="Appearance"
-/>
-```
-
-### CustomColorsSection
-
-Section component for customizing color palette.
-
-```tsx
-import { CustomColorsSection } from '@umituz/react-native-settings';
-
-function ColorCustomizer() {
-  const { customColors, setCustomColors } = useAppearanceActions();
-
-  return (
-    <CustomColorsSection
-      colors={customColors || defaultColors}
-      onColorsChange={setCustomColors}
-    />
-  );
-}
-```
-
-#### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `colors` | `ColorPalette` | **Required** | Current color palette |
-| `onColorsChange` | `(colors: ColorPalette) => void` | **Required** | Color change handler |
-| `availableColors` | `string[]` | `undefined` | Predefined color options |
-| `showPreview` | `boolean` | `true` | Show color preview |
-| `title` | `string` | `'Colors'` | Section title |
-
-#### Example
-
-```tsx
-<CustomColorsSection
-  colors={{
-    primary: '#FF5722',
-    secondary: '#2196F3',
-    accent: '#FFC107',
-    background: '#FFFFFF',
-    surface: '#F5F5F5',
-  }}
-  onColorsChange={(newColors) => {
-    setCustomColors(newColors);
-  }}
-  availableColors={[
-    '#FF5722', '#2196F3', '#4CAF50', '#FF9800',
-    '#9C27B0', '#00BCD4', '#8BC34A', '#FFC107'
-  ]}
-/>
-```
-
-### AppearancePreview
-
-Component showing live preview of theme changes.
-
-```tsx
-import { AppearancePreview } from '@umituz/react-native-settings';
-
-function ThemePreview() {
-  const { themeMode, customColors } = useAppearance();
-
-  return (
-    <AppearancePreview
-      themeMode={themeMode}
-      customColors={customColors}
-    />
-  );
-}
-```
-
-#### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `themeMode` | `'light' \| 'dark' \| 'auto'` | **Required** | Theme mode |
-| `customColors` | `ColorPalette` | `undefined` | Custom colors |
-| `showSystemTheme` | `boolean` | `true` | Show system theme |
-
-### ThemeOption
-
-Individual theme option button/card.
-
-```tsx
-import { ThemeOption } from '@umituz/react-native-settings';
-
-function ThemeOptions() {
-  return (
-    <View>
-      <ThemeOption
-        mode="light"
-        title="Light"
-        icon="sunny-outline"
-        selected={themeMode === 'light'}
-        onPress={() => setThemeMode('light')}
-      />
-
-      <ThemeOption
-        mode="dark"
-        title="Dark"
-        icon="moon-outline"
-        selected={themeMode === 'dark'}
-        onPress={() => setThemeMode('dark')}
-      />
-
-      <ThemeOption
-        mode="auto"
-        title="Auto"
-        icon="phone-portrait-outline"
-        selected={themeMode === 'auto'}
-        onPress={() => setThemeMode('auto')}
-      />
-    </View>
-  );
-}
-```
-
-#### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `mode` | `'light' \| 'dark' \| 'auto'` | **Required** | Theme mode |
-| `title` | `string` | **Required** | Theme title |
-| `icon` | `IconName` | **Required** | Theme icon |
-| `selected` | `boolean` | `false` | Selected state |
-| `onPress` | `() => void` | **Required** | Press handler |
-| `description` | `string` | `undefined` | Theme description |
-
-### ColorPicker
-
-Color picker component for selecting custom colors.
-
-```tsx
-import { ColorPicker } from '@umituz/react-native-settings';
-
-function PrimaryColorPicker() {
-  const [color, setColor] = useState('#FF5722');
-
-  return (
-    <ColorPicker
-      label="Primary Color"
-      value={color}
-      onChange={setColor}
-      availableColors={['#FF5722', '#2196F3', '#4CAF50', '#FF9800']}
-    />
-  );
-}
-```
-
-#### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `string` | **Required** | Color label |
-| `value` | `string` | **Required** | Current color (hex) |
-| `onChange` | `(color: string) => void` | **Required** | Change handler |
-| `availableColors` | `string[]` | `undefined` | Predefined colors |
-| `showCustomPicker` | `boolean` | `true` | Show custom color picker |
-| `allowAlpha` | `boolean` | `false` | Allow alpha channel |
-
-## Examples
-
-### Complete Appearance Screen
-
-```tsx
-function AppearanceScreen() {
-  const { themeMode, customColors } = useAppearance();
-  const { setThemeMode, setCustomColors, resetColors } = useAppearanceActions();
-
-  return (
-    <ScrollView>
-      <AppearancePreview
-        themeMode={themeMode}
-        customColors={customColors}
-      />
-
-      <ThemeModeSection
-        themeMode={themeMode}
-        onThemeModeChange={setThemeMode}
-        showPreview={true}
-      />
-
-      <CustomColorsSection
-        colors={customColors || defaultColors}
-        onColorsChange={setCustomColors}
-        showPreview={true}
-      />
-
-      <TouchableOpacity onPress={resetColors}>
-        <Text>Reset to Defaults</Text>
-      </TouchableOpacity>
-    </ScrollView>
-  );
-}
-```
-
-### Custom Color Palette
-
-```tsx
-function CustomThemeBuilder() {
-  const [colors, setColors] = useState(defaultColors);
-  const { setCustomColors } = useAppearanceActions();
-
-  const handleColorChange = (key: string, value: string) => {
-    setColors(prev => ({ ...prev, [key]: value }));
-  };
-
-  return (
-    <View>
-      <ColorPicker
-        label="Primary"
-        value={colors.primary}
-        onChange={(color) => handleColorChange('primary', color)}
-      />
-
-      <ColorPicker
-        label="Secondary"
-        value={colors.secondary}
-        onChange={(color) => handleColorChange('secondary', color)}
-      />
-
-      <ColorPicker
-        label="Accent"
-        value={colors.accent}
-        onChange={(color) => handleColorChange('accent', color)}
-      />
-
-      <Button
-        onPress={() => setCustomColors(colors)}
-        title="Apply Theme"
-      />
-    </View>
-  );
-}
-```
-
-### Theme Switcher
-
-```tsx
-function QuickThemeSwitcher() {
-  const { themeMode, setThemeMode } = useAppearanceActions();
-
-  return (
-    <View style={styles.container}>
-      <TouchableOpacity
-        style={[styles.option, themeMode === 'light' && styles.selected]}
-        onPress={() => setThemeMode('light')}
-      >
-        <Ionicons name="sunny" size={24} />
-        <Text>Light</Text>
-      </TouchableOpacity>
-
-      <TouchableOpacity
-        style={[styles.option, themeMode === 'dark' && styles.selected]}
-        onPress={() => setThemeMode('dark')}
-      >
-        <Ionicons name="moon" size={24} />
-        <Text>Dark</Text>
-      </TouchableOpacity>
-
-      <TouchableOpacity
-        style={[styles.option, themeMode === 'auto' && styles.selected]}
-        onPress={() => setThemeMode('auto')}
-      >
-        <Ionicons name="phone-portrait" size={24} />
-        <Text>Auto</Text>
-      </TouchableOpacity>
-    </View>
-  );
-}
-```
-
-### Preset Themes
-
-```tsx
-function ThemePresets() {
-  const { setCustomColors } = useAppearanceActions();
-
-  const presets = {
-    ocean: {
-      primary: '#2196F3',
-      secondary: '#00BCD4',
-      accent: '#4FC3F7',
-    },
-    sunset: {
-      primary: '#FF5722',
-      secondary: '#FF9800',
-      accent: '#FFC107',
-    },
-    forest: {
-      primary: '#4CAF50',
-      secondary: '#8BC34A',
-      accent: '#CDDC39',
-    },
-  };
-
-  return (
-    <View>
-      <Text>Choose a preset theme:</Text>
-
-      {Object.entries(presets).map(([name, colors]) => (
-        <TouchableOpacity
-          key={name}
-          onPress={() => setCustomColors(colors)}
-        >
-          <View style={{ flexDirection: 'row' }}>
-            <View style={{ backgroundColor: colors.primary, width: 20, height: 20 }} />
-            <View style={{ backgroundColor: colors.secondary, width: 20, height: 20 }} />
-            <View style={{ backgroundColor: colors.accent, width: 20, height: 20 }} />
-            <Text>{name}</Text>
-          </View>
-        </TouchableOpacity>
-      ))}
-    </View>
-  );
-}
-```
-
-## Styling
-
-### Theme Styles
-
-```typescript
-const styles = StyleSheet.create({
-  container: {
-    padding: tokens.spacing.lg,
-  },
-  themeOption: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    padding: tokens.spacing.md,
-    backgroundColor: tokens.colors.surface,
-    borderRadius: tokens.borderRadius.md,
-    marginBottom: tokens.spacing.sm,
-  },
-  themeOptionSelected: {
-    borderWidth: 2,
-    borderColor: tokens.colors.primary,
-  },
-  themeIcon: {
-    marginRight: tokens.spacing.md,
-  },
-  themeTitle: {
-    fontSize: tokens.typography.fontSize.base,
-    fontWeight: '600',
-    color: tokens.colors.textPrimary,
-  },
-  themeDescription: {
-    fontSize: tokens.typography.fontSize.sm,
-    color: tokens.colors.textSecondary,
-  },
-});
-```
-
-## Color Palettes
-
-### Light Theme Default
-
-```typescript
-const lightColors: ColorPalette = {
-  primary: '#2196F3',
-  secondary: '#00BCD4',
-  accent: '#FFC107',
-  background: '#FFFFFF',
-  surface: '#F5F5F5',
-  error: '#F44336',
-  success: '#4CAF50',
-  warning: '#FF9800',
-};
-```
-
-### Dark Theme Default
-
-```typescript
-const darkColors: ColorPalette = {
-  primary: '#2196F3',
-  secondary: '#00BCD4',
-  accent: '#FFC107',
-  background: '#121212',
-  surface: '#1E1E1E',
-  error: '#EF5350',
-  success: '#66BB6A',
-  warning: '#FFA726',
-};
-```
-
-## Best Practices
-
-1. **Preview**: Always show theme preview
-2. **System Theme**: Respect system preference in auto mode
-3. **Persistence**: Save theme changes immediately
-4. **Validation**: Validate color hex codes
-5. **Reset**: Provide reset to defaults
-6. **Performance**: Use smooth transitions
-7. **Accessibility**: Ensure sufficient contrast
-
-## Related
-
-- **Appearance Hooks**: Theme management hooks
-- **Appearance Services**: System theme detection
-- **Appearance Domain**: Appearance domain documentation
-
-## License
-
-MIT
+## 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