# 003: User Settings Page

## Overview

Implement a user settings page where users can manage their profile information, starting with the ability to set their display name. This phase assumes 002 (core features) is complete.

## Goals

- Create a settings page accessible from the UI
- Implement display name editing functionality
- Implement avatar upload functionality
- Add basic form validation for user inputs
- Ensure settings persist across sessions
- Set foundation for future settings additions (handle, preferences)

## Schema Updates

No new tables needed. Using existing User table from 001/002:
- `handle`: Unique username (read-only for now)
- `displayName`: User's display name (editable)
- `email`: From auth provider (read-only)
- `avatarUrl`: Profile picture URL (future implementation)

## Backend Functions (Convex)

### User Settings Operations
- **Get current user settings**: Retrieve authenticated user's profile data
  - Output: handle, displayName, email, avatarUrl
  - Permissions: Own settings only
- **Update display name**: Modify user's display name
  - Input: displayName (string)
  - Validation: Non-empty, max 50 characters, trim whitespace
  - Output: Updated user object
  - Permissions: Own settings only
- **Upload avatar**: Handle avatar image upload
  - Input: file upload (image)
  - Validation: Image type (jpg, png, gif, webp), max 5MB
  - Process: Store file, generate storage URL
  - Output: Updated user object with avatarUrl
  - Permissions: Own settings only
- **Remove avatar**: Clear user's avatar
  - Output: Updated user object with null avatarUrl
  - Permissions: Own settings only

## UI Components

### Settings Page Layout
- Accessible from user avatar/menu in app header
- Clean form-based interface
- Sections for different settings categories (Profile, Preferences, etc.)
- Save/Cancel buttons with loading states
- Success/error feedback messages

### Profile Settings Section
- **Avatar Upload**
  - Current avatar display (circular thumbnail)
  - Upload button to select new image
  - File picker limited to image types
  - Remove avatar button (if avatar exists)
  - Loading state during upload
  - Preview of selected image before upload
- **Display Name Field**
  - Text input with current value
  - Character counter (0-50)
  - Real-time validation feedback
  - Save button (only enabled when changed and valid)
- **Handle Display** (read-only for now)
  - Shows current handle
  - Helper text indicating it's not editable yet
- **Email Display** (read-only)
  - Shows authenticated email
  - Helper text indicating it's from Google account

### Navigation
- Settings accessible via:
  - User menu dropdown in header
  - Direct route: `/settings`
- Back/close button to return to previous view

## Acceptance Criteria

- [ ] Users can navigate to settings page from app header
- [ ] Settings page displays current user profile data
- [ ] Users can edit their display name
- [ ] Display name changes save successfully
- [ ] Users can upload a new avatar image
- [ ] Avatar upload shows preview before saving
- [ ] Avatar upload validates file type and size
- [ ] Users can remove their avatar
- [ ] Avatar changes reflect immediately across the app (header, messages, member list)
- [ ] Display name updates reflect immediately across the app
- [ ] Form validation prevents empty or overly long names
- [ ] Success message appears after saving changes
- [ ] Error messages appear for failed updates
- [ ] Settings page works on both desktop and mobile web
- [ ] Settings page is only accessible to authenticated users

## Technical Considerations

### Form State Management
- Use React state for form inputs
- Track "dirty" state to enable/disable save button
- Optimistic updates for better UX (revert on error)

### Validation Rules
- **Display name**:
  - Required (non-empty after trimming)
  - Max 50 characters
  - Trim whitespace before saving
  - No special validation beyond length (allow emojis, unicode, etc.)
- **Avatar upload**:
  - Allowed types: image/jpeg, image/png, image/gif, image/webp
  - Max file size: 5MB
  - Client-side validation before upload
  - Server-side validation on file storage

### Real-time Sync
- Leverage Convex's reactive queries to show updated profile data across app
- Update display name and avatar in:
  - App header/user menu
  - Message author names
  - Member lists
  - Any other user references

### File Storage
- Use Convex file storage for avatar uploads
- Store file reference (storageId) in user record
- Generate public URL for avatar display
- Consider image optimization/resizing (future enhancement)

### Mobile Responsiveness
- Settings page must work well on mobile
- Form inputs should be touch-friendly
- Consider full-screen modal on mobile vs. page on desktop

### Future Extensibility
Structure settings page to easily add:
- Handle editing (phase 004+)
- Notification preferences
- Theme/appearance preferences
- Privacy settings
- Avatar image cropping/editing

## Out of Scope (Future Phases)

- Handle/username editing
- Avatar image cropping/editing before upload
- Email change (handled by auth provider)
- Password management (using OAuth only)
- Notification preferences
- Appearance/theme preferences for user (different from space themes)
- Privacy settings
- Account deletion
- Multi-factor authentication
- Linked accounts/social profiles