# Sonic Cloud Components

This directory contains all 22 UI components for the Sonic Cloud music platform.

## Component Categories

### Audio Player (3 components)
- **AudioPlayer** - Global audio player with play/pause, progress, volume controls
- **PlayerControls** - Reusable control buttons (play, pause, next, previous, shuffle, repeat)
- **WaveformDisplay** - Visual audio waveform with seek functionality

### Cards (4 components)
- **SongCard** - Song display with cover, title, artist, play button
- **AlbumCard** - Album display with cover, title, artist, track count
- **ArtistCard** - Artist display with avatar, name, followers, verified badge
- **PlaylistCard** - Playlist display with cover, title, description, song count

### Headers (5 components)
- **ArtistHeader** - Artist profile header with banner, avatar, bio, stats
- **AlbumHeader** - Album header with cover, title, artist, release info
- **PlaylistHeader** - Playlist header with cover, title, actions
- **GenreHeader** - Genre page header with gradient background
- **SectionHeader** - Reusable section title with "See all" link

### Lists (1 component)
- **TrackList** - Song list with play buttons, position numbers, duration

### Forms (4 components)
- **AuthForm** - Login/register/forgot-password form (3 modes)
- **UploadForm** - Song upload form with file input, metadata fields
- **ProfileForm** - User profile edit form with validation
- **AvatarUpload** - Avatar image upload with drag-and-drop preview

### Search (2 components)
- **SearchBar** - Search input with autocomplete suggestions
- **SearchResults** - Search results display (songs, artists, albums)

### Modals (1 component)
- **CreatePlaylistModal** - Modal for creating new playlists

### Utility (2 components)
- **GenreBadge** - Small genre tag with variants (default, outlined, minimal)
- **SocialLinks** - Social media link icons (Twitter, Instagram, etc.)

## Design System

### Colors
- **Background**: zinc-900, zinc-950
- **Surface**: zinc-800
- **Accent**: purple-500, purple-600
- **Text**: white, zinc-100 (primary), zinc-400 (secondary)
- **Border**: zinc-700, zinc-800

### Spacing
- **Cards**: p-4 (padding)
- **Sections**: mb-6, mb-8 (margin bottom)
- **Gaps**: gap-3, gap-4, gap-6

### Border Radius
- **Small**: rounded-lg (8px)
- **Medium**: rounded-xl (12px)
- **Large**: rounded-2xl (16px)
- **Circle**: rounded-full

### Typography
- **Headings**: font-bold, font-semibold
- **Body**: font-medium (default)
- **Sizes**: text-sm, text-base, text-lg, text-xl, text-2xl

## Component Props

All components use TypeScript interfaces for type safety. Import types like this:

```tsx
import { SongCard, type SongCardProps } from '@/components'
```

## Usage Examples

### Audio Player
```tsx
import { AudioPlayer } from '@/components'

<AudioPlayer
  songId="123"
  songTitle="My Song"
  artistName="Artist Name"
  audioUrl="/audio/song.mp3"
  coverUrl="/images/cover.jpg"
  onPlayCountIncrement={() => console.log('Play counted')}
/>
```

### Song Card
```tsx
import { SongCard } from '@/components'

<SongCard
  id="123"
  title="My Song"
  artistName="Artist Name"
  coverUrl="/images/cover.jpg"
  duration={180}
  plays={1000}
  onPlay={() => console.log('Play clicked')}
/>
```

### Auth Form
```tsx
import { AuthForm } from '@/components'

<AuthForm
  mode="login"
  onSubmit={(data) => console.log(data)}
  onModeChange={(mode) => console.log('Mode changed to', mode)}
/>
```

### Search Bar
```tsx
import { SearchBar } from '@/components'

<SearchBar
  placeholder="Search..."
  onSearch={(query) => console.log('Searching for:', query)}
  suggestions={[
    { type: 'song', id: '1', title: 'Song Title', subtitle: 'Artist' }
  ]}
  onSuggestionClick={(suggestion) => console.log('Clicked:', suggestion)}
/>
```

## Accessibility

All components follow accessibility best practices:

- **Semantic HTML** - Proper element usage (button, nav, etc.)
- **ARIA labels** - Screen reader support
- **Keyboard navigation** - Tab, Enter, Escape support
- **Focus states** - Visible focus indicators
- **Color contrast** - WCAG AA compliant

## Responsive Design

Components are mobile-first and responsive:

- **Mobile**: Base styles
- **Tablet**: sm: breakpoint (640px)
- **Desktop**: md: breakpoint (768px), lg: breakpoint (1024px)

## Component States

All interactive components support:

- **Default** - Initial state
- **Hover** - Mouse hover effect
- **Focus** - Keyboard focus ring
- **Active** - Click/tap state
- **Disabled** - Non-interactive state
- **Loading** - Async operation state

## Performance

Components are optimized for performance:

- **'use client'** - Client-side rendering where needed
- **Lazy loading** - Images with proper alt text
- **Debouncing** - Search input optimized
- **Memoization** - React hooks for expensive operations

## Browser Support

Components work in all modern browsers:

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

## Related Files

- **components/index.ts** - Barrel export for all components
- **project_manifest.json** - Component definitions and dependencies
- **CLAUDE.md** - Project workflow and guidelines