immish/docs/ui-components.md

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 | Next: Theming