MyClub/DOCS/ENHANCED_MAP_IMPLEMENTATION.md

Enhanced Map Implementation

Overview

The map system has been significantly enhanced with professional styling options, club color integration, and improved flexibility.

Features

🎨 Multiple Map Styles

The application now supports 11 professional map styles, all from free, open-source providers:

Light & Minimal

• Positron - Clean light map, perfect for overlays and colored markers
• Positron No Labels - Minimal light map without labels
• OpenStreetMap (Default) - Standard OSM tiles

Dark Themes

• Dark Matter - Professional dark theme, great for night mode
• Dark No Labels - Dark map without text labels

Black & White

• Toner (B&W) - High contrast black and white, elegant and professional
• Toner Lite (B&W) - Subtle black and white style

Colorful Options

• Voyager - Balanced colors with good readability
• Terrain - Natural terrain visualization with topographic features
• Watercolor - Artistic watercolor style (unique look)

Satellite

• Satellite - Real satellite imagery from Esri

🎯 Club Color Integration

Maps now automatically integrate your club's colors:

1. Custom Markers - Map markers are generated with your primary club color
2. Color Overlay - Subtle color tint applied to maps using club colors (15% opacity)
3. Consistent Branding - Map markers match your club's visual identity

🎨 How It Works

Custom SVG Markers

• Dynamically generated markers with club primary color
• White center dot for visibility
• Drop shadow for depth
• Professional appearance

Color Overlay System

• Uses CSS blend modes (multiply) for natural color mixing
• 15% opacity ensures map remains readable
• Automatically applied when club colors are set

📍 Where Maps Appear

Maps with enhanced styling appear in:

• Homepage - Contact section (if enabled in settings)
• Contact Page - Location map with club colors
• Events - Event location maps with geocoding
• Admin Preview - Real-time preview in contact settings

🛠️ Admin Configuration

Location in Admin Panel

Navigate to: Admin → Kontakty → Nastavení polohy

Configuration Options

1. Map Coordinates

   • Latitude/Longitude (manual entry or map link import)
   • Import from Google Maps, Mapy.cz, or other providers
   • Zoom level (1-20)

2. Map Style Selection

   • Visual selector with descriptions
   • Live preview with club colors
   • Tips for best style choices

3. Club Colors

   • Automatically pulled from general settings
   • Shows color preview in selector
   • Applied to all maps across the site

4. Homepage Display

   • Toggle map visibility on homepage
   • Full preview before publishing

📦 Technical Implementation

Files Modified

• frontend/src/components/home/ContactMap.tsx - Core map component
• frontend/src/components/admin/MapStyleSelector.tsx - New style selector UI
• frontend/src/pages/admin/ContactsAdminPage.tsx - Admin interface updates
• frontend/src/components/home/ContactsSection.tsx - Homepage integration
• frontend/src/pages/ContactPage.tsx - Contact page integration

Key Features

• Dynamic Loading - Leaflet loaded on-demand (no bloat)
• Caching - Map tiles are cached by browser
• Responsive - Mobile-friendly controls
• Accessibility - Keyboard navigation support

🎯 Style Recommendations

For Clubs with Bold Colors:

• Use Positron or Toner Lite as base
• Let your club colors shine through the overlay

For Dark/Night Mode Sites:

• Dark Matter or Dark No Labels
• Excellent contrast with light markers

For Classic/Traditional Look:

• Toner (B&W) for elegant, timeless appearance
• High contrast, professional

For Modern/Vibrant Sites:

• Voyager for balanced colors
• Watercolor for unique artistic touch

🔧 Customization

Adding New Styles

Edit MAP_STYLES in ContactMap.tsx:

'your-style-key': {
  name: 'Your Style Name',
  url: 'https://tile-server.com/{z}/{x}/{y}.png',
  attribution: '© Provider',
  description: 'Style description'
}

Changing Color Overlay Opacity

In ContactMap.tsx, adjust this line:

pane.style.opacity = '0.15'; // Change from 0.15 to your preference (0.0 - 1.0)

Custom Marker Colors

Markers automatically use clubPrimaryColor prop. To override:

<ContactMap 
  clubPrimaryColor="#YOUR_COLOR"
  // ... other props
/>

🌍 Open Source Map Providers

All map tiles are from free, open-source providers:

• CartoDB - Positron, Dark Matter, Voyager
• Stadia Maps - Toner, Terrain, Watercolor (Stamen designs)
• OpenStreetMap - Default OSM tiles
• Esri - Satellite imagery

No API keys required! All tiles are freely available.

✨ Best Practices

1. Choose Style That Matches Your Brand

   • Light maps for colorful clubs
   • Dark maps for professional/elegant sites
   • B&W for timeless, clean look

2. Test Visibility

   • Ensure markers are visible on your chosen style
   • Check readability of labels
   • Preview on mobile devices

3. Color Harmony

   • Primary color should contrast with map style
   • Use color wheel to find complementary colors
   • Test with color overlay enabled

4. Performance

   • Maps lazy-load automatically
   • Tiles are cached by browser
   • No performance impact until map is viewed

🎨 Example Configurations

Classic Football Club (Red/White)

Style: Toner Lite (B&W)
Primary Color: #e11d48 (red)
Secondary: #ffffff (white)
→ Red markers on clean B&W map

Modern Tech-Forward Club (Blue)

Style: Dark Matter
Primary Color: #3b82f6 (blue)
Secondary: #60a5fa (light blue)
→ Sleek dark map with bright blue markers

Traditional/Heritage Club (Green/Gold)

Style: Terrain
Primary Color: #16a34a (green)
Secondary: #fbbf24 (gold)
→ Natural terrain with club colors

🐛 Troubleshooting

Map doesn't load:

• Check browser console for errors
• Ensure coordinates are valid (-90 to 90 lat, -180 to 180 lng)
• Check internet connection (tiles loaded from external servers)

Marker wrong color:

• Verify club primary color is set in Settings → Vzhled
• Check color format (hex, rgb, or named colors)

Map tiles not loading:

• Some tile servers may be temporarily down
• Try different map style
• Check browser ad-blocker/privacy settings

Color overlay too strong/weak:

• Adjust opacity in ContactMap.tsx (see Customization section)
• Values: 0.05 (subtle) to 0.30 (strong)

📈 Future Enhancements

Potential additions:

• Multiple markers for multiple locations
• Custom marker icons (club logo)
• Drawing tools for catchment areas
• Route planning integration
• Cluster markers for many locations

---

Implementation Date: 2025-10-10
Version: 1.0
Status: ✅ Production Ready