add docs part 2
This commit is contained in:
444
docs/ui-components.md
Normal file
444
docs/ui-components.md
Normal file
@@ -0,0 +1,444 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user