dawarich/JAVASCRIPT_FEATURES.md

Dawarich JavaScript Features Documentation

This document provides a detailed overview of all JavaScript features implemented in the Dawarich application, organized by functionality.

Table of Contents

• Map Features
• Routes & Tracks
• Visits Management
• Areas
• Photos Integration
• Live Mode
• Visualization Features
• Search & Navigation
• Family Sharing
• Controllers

---

Map Features

Main Maps Controller (maps_controller.js)

The primary controller managing all map interactions and visualizations.

Core Functionality

• Map Initialization

  • Leaflet.js-based interactive map
  • Multiple base layer support (OpenStreetMap, custom tiles)
  • User-preferred layer persistence
  • PostGIS coordinate system support
  • Custom panes for z-index management

• Layer Management

  • Points layer (location markers)
  • Routes layer (polylines)
  • Tracks layer (GPS tracks)
  • Heatmap layer
  • Fog of War layer
  • Scratch map layer (visited countries)
  • Areas layer (user-defined regions)
  • Photos layer (geotagged images)
  • Visits layer (detected location visits)
  • Family members layer

• Settings Panel

  • Route opacity adjustment (10-100%)
  • Fog of War radius customization
  • Time/distance thresholds for route splitting
  • Points rendering mode (raw/simplified)
  • Live map toggle
  • Speed-colored routes configuration
  • Speed color scale editor with gradient stops

• Calendar Panel

  • Year selection dropdown
  • Month navigation grid
  • Tracked months visualization
  • Visited cities display
  • Date range filtering

• Scale & Stats Control

  • Distance scale (km/miles)
  • Total distance display
  • Points count display
  • Dynamic unit conversion

---

Routes & Tracks

Routes (maps/polylines.js)

Features

• Intelligent Route Splitting

  • Distance-based splitting (meters between points)
  • Time-based splitting (minutes between points)
  • Configurable thresholds

• Speed Visualization

  • Color-coded routes based on GPS velocity
  • Customizable color gradient scale
  • Speed ranges: 0-15 km/h (green), 15-30 km/h (cyan), 30-50 km/h (magenta), 50-100 km/h (yellow), 100+ km/h (red)
  • Real-time gradient editor

• Interactive Features

  • Hover highlighting with increased opacity
  • Click to lock selection
  • Start/end markers (🚥 and 🏁)
  • Popup with route details:
    • Start and end timestamps
    • Duration (days, hours, minutes)
    • Total distance
    • Current segment speed

• Performance Optimizations

  • Canvas renderer for large datasets
  • Batch processing for updates
  • Custom pane management (z-index 450)

Tracks (maps/tracks.js)

GPS tracks represent processed and analyzed routes with elevation data.

Features

• Track Visualization

  • Distinct red color (vs blue routes)
  • Elevated pane (z-index 460)
  • Start (🚀) and end (🎯) markers

• Track Information Display

  • Start/end timestamps
  • Duration
  • Distance
  • Average speed
  • Elevation gain/loss
  • Max/min altitude

• Real-time Updates

  • WebSocket integration via TracksChannel
  • Incremental track updates (create/update/delete)
  • Time range filtering
  • Memory-efficient updates

---

Visits Management

Visits System (maps/visits.js)

Advanced location visit detection and management system.

Core Features

• Visit Detection

  • Automatic visit suggestions based on dwell time
  • Confirmed vs suggested visits (separate layers)
  • Custom panes for proper z-index ordering
  • Visual distinction (blue for confirmed, orange/dashed for suggested)

• Area Selection Tool

  • Click-and-drag rectangle selection
  • Filter visits within selected area
  • Points within bounds calculation
  • Date-grouped summary panel

• Visit Drawer UI

  • Sliding side panel
  • Hierarchical visit list
  • Visit status indicators
  • Quick actions (confirm/decline)

• Visit Operations

  • Confirm suggested visits
  • Decline unwanted visits
  • Merge multiple visits
  • Bulk operations (confirm/decline multiple)
  • Delete visits with confirmation
  • Edit visit name and location

• Interactive Features

  • Checkbox selection with smart visibility
  • Adjacent visit highlighting
  • Map circle highlighting on hover
  • Click visit to center map
  • Possible places dropdown
  • Duration formatting

• Visit Details

  • Name and address
  • Start and end timestamps
  • Duration estimation
  • Location coordinates
  • City, state, country
  • Status (suggested/confirmed/declined)

---

Areas

Area Management (maps/areas.js)

User-defined geographic areas for visit tracking.

Features

• Area Creation

  • Leaflet.draw integration
  • Circle drawing tool
  • Interactive popup form
  • Name input validation
  • Custom pane (z-index 605)

• Area Display

  • Red circle markers
  • Semi-transparent fill
  • Hover effects (increased opacity)
  • Click to show details

• Area Information

  • Name
  • Radius (meters)
  • Center coordinates
  • Area ID badge

• Area Management

  • Delete confirmation
  • Theme-aware styling
  • API integration for CRUD operations

---

Photos Integration

Photo Layer (maps/photos.js)

Integration with Immich and Photoprism for geotagged photos.

Features

• Photo Sources

  • Immich integration
  • Photoprism integration
  • Source URL configuration

• Photo Markers

  • 48x48px thumbnail markers
  • Lazy loading with retry logic
  • Loading spinner animation
  • Error handling

• Photo Popups

  • Full thumbnail preview
  • Original filename
  • Capture timestamp
  • Location (city, state, country)
  • Source system link
  • Type indicator (📷 photo / 🎥 video)
  • Hover shadow effects

• Performance

  • Promise-based loading
  • Progressive rendering
  • Automatic retry (3 attempts)
  • Date range filtering

---

Live Mode

Live Map Handler (maps/live_map_handler.js)

Real-time GPS tracking with memory-efficient streaming.

Features

• Memory Management

  • Bounded data structures (max 1000 points)
  • Automatic old point removal
  • Prevents memory leaks
  • Incremental updates

• Real-time Updates

  • WebSocket integration (PointsChannel)
  • Live marker addition
  • Incremental polyline segments
  • Heatmap updates
  • Auto-pan to new location

• Layer Synchronization

  • Markers layer updates
  • Polylines layer incremental updates
  • Heatmap point management
  • Fog of War updates

• Performance

  • No full layer recreation
  • Direct marker references
  • Efficient last marker tracking
  • Smart cleanup on disable

---

Visualization Features

Fog of War (maps/fog_of_war.js)

Gamification feature showing unexplored areas.

Features

• Canvas-based Rendering

  • Overlay at z-index 400
  • RGBA fog layer (0,0,0,0.4)
  • destination-out composite operation
  • Responsive to map size changes

• Smart Fog Clearing

  • Circular cleared areas around points
  • Line connections between nearby points
  • Configurable clear radius (meters)
  • Time threshold for connections
  • Rounded line caps and joins

• Dynamic Updates

  • Pan and zoom responsive
  • Real-time recalculation
  • Map resize handling
  • Stored parameters for efficiency

Scratch Map (maps/scratch_layer.js)

World map showing visited countries.

Features

• Country Visualization

  • GeoJSON country borders
  • Golden overlay (fillColor: #FFD700)
  • Orange borders (color: #FFA500)
  • ISO 3166-1 Alpha-2 code matching

• Data Management

  • Country code mapping
  • Unique country extraction
  • Cached world borders data
  • Automatic refresh

• Integration

  • Layer control toggle
  • Marker data updates
  • Visibility state tracking

Heatmap

Built-in Leaflet.heat plugin for density visualization.

• Configuration
  • 20px radius
  • 0.2 intensity per point
  • Automatic color gradient
  • Layer control toggle

---

Search & Navigation

Location Search (maps/location_search.js)

Advanced location search with visit history.

Features

• Search Interface

  • Inline search bar (400px wide)
  • Search toggle button with Lucide icon
  • Keyboard shortcuts (Enter, Escape, Arrow keys)
  • Click-outside-to-close
  • Auto-position next to button

• Suggestions System

  • Real-time autocomplete (300ms debounce)
  • Keyboard navigation (↑↓ arrows)
  • Suggestion highlighting
  • 2-character minimum query

• Search Results

  • Hierarchical results (location → years → visits)
  • Collapsible year sections
  • Visit count per location
  • Date range display
  • Duration estimates

• Visit Navigation

  • Click visit to zoom and highlight
  • Time filter events
  • 4-hour window around visit
  • Special visit markers (green circles)

• Visit Creation

  • Create visit from search result
  • Pre-filled form with location data
  • Datetime picker for start/end
  • Duration calculation
  • Validation

• Map Integration

  • Position relative to button
  • Maintains position during map pan/zoom
  • Prevents map scroll interference
  • Visits layer refresh after creation

---

Family Sharing

Family Members Controller (family_members_controller.js)

Real-time family member location sharing.

Features

• Family Member Markers

  • Circular avatars with email initials
  • Green color scheme (#10B981)
  • White border and shadow
  • Distinct from other markers

• Real-time Updates

  • ActionCable integration (FamilyLocationsChannel)
  • Incremental position updates
  • Recent update animation (< 5 minutes)
  • Pulse effect for active updates

• Location Information

  • Email address
  • Coordinates (6 decimal precision)
  • Battery level with colored icons
  • Battery status (charging/full)
  • Last seen timestamp

• Battery Indicators

  • Lucide battery icons
  • Color-coded: red (≤20%), orange (≤50%), green (>50%)
  • Charging icon when plugged in
  • Full battery indicator

• Map Integration

  • Permanent tooltips (last seen + battery)
  • Detailed popups on click
  • Theme-aware styling
  • Auto-zoom to fit all members
  • Layer control integration

• Refresh Management

  • 60-second periodic refresh (fallback)
  • Manual refresh button
  • Automatic stop when layer disabled
  • User feedback on manual refresh

---

Controllers

Base Controller (base_controller.js)

Common functionality for all Stimulus controllers.

Other Controllers

• datetime_controller.js: Date/time picker initialization
• imports_controller.js: File import progress tracking
• trips_controller.js: Trip management UI
• stat_page_controller.js: Statistics page interactions
• clipboard_controller.js: Copy-to-clipboard functionality
• notifications_controller.js: Real-time notifications
• sharing_modal_controller.js: Public sharing UI
• map_preview_controller.js: Embedded map previews
• visit_modal_map_controller.js: Visit creation map
• add_visit_controller.js: Visit addition flow
• public_stat_map_controller.js: Public stat sharing maps

---

Technical Details

Map Controls & UI

• Top-Right Buttons (maps/map_controls.js)

  • Select Area tool
  • Add Visit button
  • Calendar toggle
  • Visits drawer toggle
  • Consistent ordering and styling

• Theme Support (maps/theme_utils.js)

  • Dark/light theme detection
  • Automatic control styling
  • Button theme adaptation
  • Panel theme colors
  • Oklahoma-based color system

Helper Functions (maps/helpers.js)

• Date Formatting: Timezone-aware timestamp conversion
• Distance Formatting: km/miles with proper units
• Speed Formatting: km/h or mph conversion
• Duration Formatting: Days, hours, minutes display
• Haversine Distance: Accurate geographic distance calculation
• Flash Messages: User notification system

Markers (maps/markers.js, maps/marker_factory.js)

• Standard Markers: CircleMarkers with popups
• Live Markers: Optimized for streaming
• Popup Content: Delete button, coordinates, timestamp, battery, velocity
• Marker Clustering: Performance optimization for large datasets

Layers Configuration (maps/layers.js)

• Raster Maps (raster_maps_config.js)

  • OpenStreetMap
  • Stadia Maps (Alidade Smooth)
  • CartoDB
  • Stamen

• Vector Maps (vector_maps_config.js)

  • Self-hosted vector tiles
  • Optional fallback system

Performance Monitoring

• Tile Monitor (maps/tile_monitor.js)
  • Track tile load times
  • Identify slow tiles
  • Performance metrics API

---

WebSocket Channels

PointsChannel (channels/points_channel.js)

Real-time GPS point streaming for live mode.

TracksChannel

Real-time track updates (create/update/delete).

FamilyLocationsChannel (channels/family_locations_channel.js)

Real-time family member location updates.

NotificationsChannel (channels/notifications_channel.js)

System notifications and alerts.

ImportsChannel (channels/imports_channel.js)

Import progress updates.

---

Key Technologies

• Leaflet.js: Core mapping library
• Stimulus: JavaScript framework
• Hotwired Turbo: SPA-like navigation
• ActionCable: WebSocket integration
• Canvas API: High-performance rendering
• GeoJSON: Geographic data format
• PostGIS: Spatial database queries

---

Configuration

Map features are controlled through user settings:

• route_opacity: Route visibility (0.0-1.0)
• fog_of_war_meters: Fog clear radius
• fog_of_war_threshold: Seconds between fog lines
• meters_between_routes: Route split distance
• minutes_between_routes: Route split time
• time_threshold_minutes: Visit detection threshold
• merge_threshold_minutes: Visit merge threshold
• points_rendering_mode: Raw or simplified
• live_map_enabled: Enable live mode
• speed_colored_routes: Enable speed colors
• speed_color_scale: Custom gradient definition
• preferred_map_layer: Base layer selection
• enabled_map_layers: Active overlay layers
• maps.distance_unit: km or mi
• maps.url: Custom tile server
• immich_url: Immich server
• photoprism_url: Photoprism server

---

Data Flow

1. Initial Load: Server renders map with data attributes
2. Controller Connect: Stimulus initializes map and layers
3. User Interaction: Events trigger controller methods
4. API Calls: Fetch/update data via REST API
5. WebSocket Updates: Real-time data via ActionCable
6. Layer Updates: Incremental map updates
7. Settings Persistence: API saves user preferences

---

Memory Management

• Bounded arrays for live mode (max 1000 points)
• Marker reference tracking for efficient updates
• Layer cleanup on disconnect
• Event listener removal
• Canvas context management
• GeoJSON data caching

---

Accessibility Features

• Keyboard navigation for search
• Theme-aware color schemes
• Clear visual indicators
• Tooltip descriptions
• Confirmation dialogs for destructive actions
• Error message display
• Loading states

---

Future Enhancements

Potential areas for expansion:

• Route editing capabilities
• Custom area shapes (polygons)
• Enhanced photo filtering
• Route comparison tools
• Advanced track statistics
• Export to GPX/GeoJSON
• Offline map support
• Route planning
• Custom marker icons
• Geofencing alerts