AudiOhm/frontend/SETTINGS_PAGE_README.md

# Settings Page Implementation - Spotify Le 2

## Overview
Complete Settings Page implementation with neon cyberpunk theme for user profile management, audio settings, and app preferences.

## Files Created

### 1. Provider Layer
**File:** `frontend/lib/presentation/providers/settings_provider.dart`

Features:
- **SettingsState**: Manages user data, audio quality, download preferences, and cache
- **SettingsNotifier**: Handles all settings operations
  - Load user profile from API
  - Update profile (display name, avatar URL)
  - Audio quality management (Low/Medium/High/Lossless)
  - Cache calculation and clearing
  - Persistent settings with SharedPreferences
- **AudioQuality Enum**: low, medium, high, lossless

### 2. Widgets Layer

#### `frontend/lib/presentation/widgets/settings/settings_tile.dart`
Reusable components:
- **SettingsTile**: Basic settings item with title, subtitle, icon, and trailing widget
- **SettingsToggleTile**: Settings item with toggle switch
- **SettingsSectionHeader**: Section title with uppercase styling
- **SettingsCard**: Container with neon glow border

#### `frontend/lib/presentation/widgets/settings/profile_section.dart`
Features:
- User avatar with gradient glow
- Display name, username, and email
- Premium badge indicator
- Edit Profile button
- Gradient background with cyberpunk styling

#### `frontend/lib/presentation/widgets/settings/audio_quality_selector.dart`
Features:
- Four audio quality options (Low/Medium/High/Lossless)
- Bitrate display (96/160/320 kbps / FLAC)
- Premium lock for Lossless quality
- Visual selection indicator
- Description for each quality level

#### `frontend/lib/presentation/widgets/settings/cache_management_tile.dart`
Features:
- Cache size calculation and display
- Format bytes (B/KB/MB/GB)
- Clear cache button with confirmation dialog
- Loading state during cache clearing
- Success/error snackbar notifications

#### `frontend/lib/presentation/widgets/settings/edit_profile_dialog.dart`
Features:
- Edit display name
- Avatar image picker
- Image preview
- Save/Cancel buttons
- Validation and error handling
- Note about server-side avatar upload

### 3. Page Layer

**File:** `frontend/lib/presentation/pages/settings/settings_page.dart`

Complete settings page with sections:
- **Profile Section**: User info with avatar
- **Audio Section**: Audio quality selector
- **Playback Section**:
  - Crossfade toggle with duration slider
  - Gapless playback toggle
  - Normalize volume toggle
- **Downloads Section**:
  - Download on mobile data toggle
  - Show explicit content toggle
- **Storage Section**: Cache management
- **About Section**:
  - App version (with package_info_plus)
  - Licenses page
- **Logout**: Confirmation dialog

## Dependencies Added

```yaml
package_info_plus: ^5.0.1  # For app version info
image_picker: ^1.0.7        # For avatar image selection
```

## Key Features

### 1. Persistent Storage
All settings are persisted using SharedPreferences:
- Audio quality
- Download on mobile data
- Show explicit content
- Crossfade settings
- Gapless playback
- Normalize volume

### 2. Cache Management
- Automatic cache size calculation
- Temporary and documents directory scanning
- Human-readable size formatting
- Clear cache functionality

### 3. Profile Management
- Integration with AuthApiService
- Load profile from `/api/v1/auth/me`
- Update profile with PUT request
- Display name and avatar URL updates
- Error handling with snackbar notifications

### 4. Neon Cyberpunk Theme
- Cyan glow effects
- Gradient backgrounds
- Border styling with transparency
- Custom toggle switches
- Elevated and outlined button styles
- Consistent with existing app theme

### 5. Responsive Design
- CustomScrollView with SliverAppBar
- Card-based layout
- Proper spacing and padding
- Responsive width constraints
- Mobile-optimized

## API Integration

### GET /api/v1/auth/me
```dart
final user = await _authApiService.getCurrentUser();
```

### PUT /api/v1/auth/me
```dart
final updatedUser = await _authApiService.updateProfile(
  displayName: displayName,
  avatarUrl: avatarUrl,
);
```

## Usage Example

### Navigate to Settings Page
```dart
Navigator.push(
  context,
  MaterialPageRoute(
    builder: (context) => const SettingsPage(),
  ),
);
```

### Using Settings Provider
```dart
final settingsState = ref.watch(settingsProvider);

// Update audio quality
ref.read(settingsProvider.notifier).setAudioQuality(AudioQuality.high);

// Toggle setting
ref.read(settingsProvider.notifier).toggleCrossfade(true);

// Update profile
await ref.read(settingsProvider.notifier).updateProfile(
  displayName: 'New Name',
);

// Clear cache
await ref.read(settingsProvider.notifier).clearCache();
```

## Theme Integration

All widgets follow the neon cyberpunk theme:
- **Primary Colors**: Cyan (#00F0FF), Violet (#BF00FF), Rose (#FF006E)
- **Backgrounds**: Dark blue tones (#0A0E27, #1A1F3A)
- **Text**: OnBackground (#E0E6FF), OnSurface (#B0B8D4)
- **Effects**: Glow shadows, gradients, borders

## Error Handling

- Network errors caught and displayed
- Snackbar notifications for user feedback
- Loading states during async operations
- Validation for profile updates
- Graceful fallbacks for missing data

## Future Enhancements

1. **Avatar Upload**: Implement server-side image upload
2. **Equalizer**: Add customizable EQ presets
3. **Language**: Add language selector
4. **Theme**: Add light/dark theme toggle
5. **Notifications**: Add notification settings
6. **Privacy**: Add privacy settings page
7. **Account**: Add account deletion
8. **Social**: Add social links management

## Testing Recommendations

1. **Profile Updates**: Test display name changes
2. **Audio Quality**: Test all quality levels
3. **Cache**: Test cache clearing on different devices
4. **Toggles**: Test all toggle switches persist
5. **Logout**: Test logout flow
6. **Network**: Test with poor network conditions
7. **Validation**: Test empty display names
8. **Image Picker**: Test on iOS and Android

## File Structure

```
frontend/lib/
├── presentation/
│   ├── providers/
│   │   └── settings_provider.dart
│   ├── pages/
│   │   └── settings/
│   │       └── settings_page.dart
│   └── widgets/
│       └── settings/
│           ├── settings_tile.dart
│           ├── profile_section.dart
│           ├── audio_quality_selector.dart
│           ├── cache_management_tile.dart
│           ├── edit_profile_dialog.dart
│           └── settings_widgets.dart
```

## Notes

- Avatar upload requires server implementation
- Image picker requires permissions in AndroidManifest.xml and Info.plist
- Cache clearing may take time on large caches
- Premium features should be validated on backend
- Audio quality changes should take effect on next track load