445 lines
15 KiB
Markdown
445 lines
15 KiB
Markdown
# 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)
|