# UI Components

Reusable UI components used throughout the app.

## Asset Display Components

### Thumbnail Tile

Displays a single asset thumbnail in grids.

**Properties:**
- asset: Asset to display
- showStorageIndicator: Show local/remote badge
- onTap: Tap handler
- onLongPress: Long press handler (selection)
- isSelected: Selection state

**Visual States:**
```
Normal:              Selected:
┌──────────┐         ┌──────────┐
│          │         │ ┌──────┐ │
│  [Image] │         │ │Image │✓│
│          │         │ └──────┘ │
│      [●] │         │      [●] │
└──────────┘         └──────────┘
     └─ Storage           └─ Checkmark
        indicator            overlay
```

**Storage Indicators:**
- Cloud icon: Remote only
- Device icon: Local only
- Cloud+Device: Both (merged)

**Overlay Badges:**
- Video duration (bottom left)
- Stack count (bottom right)
- Favorite heart (top right)

### Thumbnail Image

Loads and displays asset images with progressive loading.

**Loading States:**
1. Show thumbhash placeholder (blurred)
2. Load thumbnail quality
3. Optionally load preview quality
4. Optionally load original

**Caching:**
- Uses image cache
- Key: asset ID + quality level
- Respects cache size limits

### Asset Grid

Displays assets in a scrollable grid.

**Properties:**
- assets: List of assets
- tilesPerRow: Column count (2-6)
- onAssetTap: Individual tap handler
- onSelectModeChanged: Selection mode callback
- enableMultiSelect: Allow multi-selection

**Features:**
- Virtualized scrolling (only renders visible items)
- Grouped by date with section headers
- Pull-to-refresh support
- Drag to scroll with date indicator

### Draggable Scrollbar

Custom scrollbar with date indicator.

**Components:**
```
┌─────────────────────────┬─┐
│                         │▲│
│                         ├─┤
│  [Asset Grid]           │ │
│                         │█│← Thumb
│                         │ │  ┌──────────┐
│                         │ │  │ Jan 2024 │← Date bubble
│                         │ │  └──────────┘
│                         │ │
│                         ├─┤
│                         │▼│
└─────────────────────────┴─┘
```

**Behaviors:**
- Drag thumb to fast scroll
- Date bubble shows current position
- Auto-hide when not interacting
- Haptic feedback on date changes

## Navigation Components

### Bottom Navigation Bar

Main app navigation.

**Tabs:**
```
┌─────────────────────────────────────┐
│  [Photos]  [Search]  [Sharing]  [Library]  │
│     ●        ○          ○         ○        │
└─────────────────────────────────────┘
```

**States:**
- Selected: Filled icon + label
- Unselected: Outline icon

### App Bar

Standard navigation header.

**Variants:**

Default:
```
┌─────────────────────────────────────┐
│  [←]  Title                  [⋮]   │
└─────────────────────────────────────┘
```

Selection mode:
```
┌─────────────────────────────────────┐
│  [✕]  3 selected      [Share][⋮]   │
└─────────────────────────────────────┘
```

### Tab Bar

Secondary navigation within screens.

```
┌─────────────────────────────────────┐
│  Albums    │    Shared    │         │
│ ──────────  ──────────────          │
└─────────────────────────────────────┘
```

## Form Components

### Text Input

Standard text field with decorations.

**States:**
- Enabled: Normal appearance
- Focused: Primary color border
- Error: Red border + error message
- Disabled: Grayed out

**Layout:**
```
┌─────────────────────────────────────┐
│  Label                              │
│  ┌───────────────────────────────┐  │
│  │ [Icon] Placeholder text   [X] │  │
│  └───────────────────────────────┘  │
│  Helper or error text               │
└─────────────────────────────────────┘
```

### Search Bar

Specialized input for search.

```
┌─────────────────────────────────────┐
│  ┌───────────────────────────────┐  │
│  │ [🔍] Search photos...     [X] │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘
```

**Features:**
- Search icon prefix
- Clear button when has text
- Debounced input for API calls

### Settings Tiles

Various settings input components.

**Switch Tile:**
```
┌─────────────────────────────────────┐
│  Setting Title                [═══] │
│  Description text                   │
└─────────────────────────────────────┘
```

**Slider Tile:**
```
┌─────────────────────────────────────┐
│  Setting Title                  4   │
│  ──────●────────────────────────    │
└─────────────────────────────────────┘
```

**Radio Tiles:**
```
┌─────────────────────────────────────┐
│  ○  Option 1                        │
│  ●  Option 2 (selected)             │
│  ○  Option 3                        │
└─────────────────────────────────────┘
```

**Button Tile:**
```
┌─────────────────────────────────────┐
│  [Icon]  Action Title           [>] │
│          Description                │
└─────────────────────────────────────┘
```

## User Interface

### User Circle Avatar

Displays user profile picture or initials.

**Properties:**
- user: User object
- size: Diameter in pixels

**Rendering:**
1. If user has profile image → show image
2. Otherwise → show initials on colored background
3. Avatar color derived from user ID

**Sizes:**
- Small: 30px (comments, lists)
- Medium: 44px (activity tiles)
- Large: 80px (profile page)

### User List Tile

Displays user in a list.

```
┌─────────────────────────────────────┐
│  [Avatar]  User Name                │
│            user@email.com           │
└─────────────────────────────────────┘
```

## Feedback Components

### Loading Indicators

**Circular Progress:**
- Indeterminate: Spinning animation
- Determinate: Shows percentage

**Linear Progress:**
```
┌─────────────────────────────────────┐
│  ████████░░░░░░░░░░░  40%          │
└─────────────────────────────────────┘
```

**Skeleton Loader:**
```
┌──────┐ ┌──────┐ ┌──────┐
│░░░░░░│ │░░░░░░│ │░░░░░░│
│░░░░░░│ │░░░░░░│ │░░░░░░│
└──────┘ └──────┘ └──────┘
```

### Snackbar

Temporary notification at bottom.

```
┌─────────────────────────────────────┐
│  Message text here          [ACTION]│
└─────────────────────────────────────┘
```

**Types:**
- Info: Default colors
- Success: Green tint
- Error: Red tint
- Warning: Orange tint

### Dialog

Modal overlay for confirmations.

```
┌─────────────────────────────────────┐
│                                     │
│  ┌───────────────────────────────┐  │
│  │          Dialog Title         │  │
│  ├───────────────────────────────┤  │
│  │                               │  │
│  │  Dialog content goes here    │  │
│  │                               │  │
│  ├───────────────────────────────┤  │
│  │         [Cancel] [Confirm]    │  │
│  └───────────────────────────────┘  │
│                                     │
└─────────────────────────────────────┘
        (dimmed background)
```

### Bottom Sheet

Slides up from bottom.

```
┌─────────────────────────────────────┐
│                                     │
│                                     │
│           (main content)            │
│                                     │
├─────────────────────────────────────┤
│  ───────  (drag handle)             │
│                                     │
│  Bottom sheet content               │
│                                     │
│  [Action 1]                         │
│  [Action 2]                         │
│  [Action 3]                         │
│                                     │
└─────────────────────────────────────┘
```

**Behaviors:**
- Drag handle to resize/dismiss
- Can expand to full screen
- Dismissible by dragging down

## Photo Viewer Components

### Top Control Bar

Overlay controls on asset viewer.

```
┌─────────────────────────────────────┐
│  [←]  filename.jpg    [♡] [⋮]       │
└─────────────────────────────────────┘
```

**Actions:**
- Back: Return to grid
- Favorite: Toggle favorite
- More: Show action menu

### Bottom Control Bar

Additional actions for current asset.

```
┌─────────────────────────────────────┐
│  [Share] [Archive] [Delete] [More]  │
└─────────────────────────────────────┘
```

### EXIF Panel

Shows metadata when expanded.

```
┌─────────────────────────────────────┐
│  Details                            │
├─────────────────────────────────────┤
│  📅  January 15, 2024  3:30 PM     │
│  📷  iPhone 15 Pro                  │
│  🔧  f/1.8  1/120s  ISO 100        │
│  📍  New York, United States        │
└─────────────────────────────────────┘
```

## Map Components

### Map View

Displays assets on a map.

**Features:**
- Cluster markers for grouped assets
- Tap cluster to zoom
- Tap marker to show asset
- Map style (light/dark/satellite)

### Map Settings Sheet

Filter controls for map.

```
┌─────────────────────────────────────┐
│  Map Settings                       │
├─────────────────────────────────────┤
│  Show favorites only         [═══]  │
│  Include archived            [═══]  │
│  Include partner photos      [═══]  │
│                                     │
│  Time Range:                        │
│  [All Time          ▼]              │
└─────────────────────────────────────┘
```

## Album Components

### Album Thumbnail

Album preview with cover image.

```
┌─────────────────────────────────────┐
│  ┌───────────────────────────────┐  │
│  │                               │  │
│  │        [Cover Image]         │  │
│  │                               │  │
│  └───────────────────────────────┘  │
│  Album Name                         │
│  50 items                           │
└─────────────────────────────────────┘
```

### Album App Bar

Album-specific header with actions.

```
┌─────────────────────────────────────┐
│  [←]  Album Name      [Share] [⋮]   │
└─────────────────────────────────────┘
```

---

[Previous: Error Handling](error-handling.md) | [Next: Theming](theming.md)