MyClub/DOCS/ACTIVITY_ADMIN_MAP_ENHANCEMENT.md

# Activity Admin Page - Map Enhancement

## 🎯 What Was Changed

Enhanced the **Admin → Aktivity (Události)** page with professional map tools, replacing the basic Mapy.com search with a full featured location system.

## ✅ Changes Made

### 1. **Replaced Mapy.com Search with MapLinkImporter**

**Before:**
- Basic text input with Mapy.com suggestions
- No visual feedback
- No coordinate extraction

**After:**
- ✅ **MapLinkImporter** tool (same as Setup page)
- ✅ Import from Google Maps, Mapy.cz, OpenStreetMap links
- ✅ Automatic coordinate extraction
- ✅ Visual confirmation

### 2. **Added Live Map Preview**

When coordinates are imported:
- ✅ Shows live map with event location
- ✅ Uses club colors for marker
- ✅ Displays event title and location
- ✅ 300px preview height
- ✅ Shows exact coordinates
- ✅ Cancel button to clear coordinates

### 3. **Improved UI Organization**

**New Section Structure:**
```
Místo konání
├── MapLinkImporter (import from URL)
├── Název místa / Adresa (text input + suggestions)
├── Typ (event type selector)
└── Map Preview (when coordinates available)
```

### 4. **Enhanced Location Input**

- Kept Mapy.com suggestions (still works)
- Added better placeholder text
- Better helper text
- Wider input field (flex 2 vs flex 1 for type)

---

## 🎨 How It Works

### Step 1: Import Coordinates (Optional but Recommended)

User can paste any map link:
```
Google Maps: https://maps.google.com/...
Mapy.cz: https://mapy.cz/...
OpenStreetMap: https://www.openstreetmap.org/...
```

**MapLinkImporter extracts:**
- Latitude
- Longitude
- Zoom level (optional)

### Step 2: Enter Location Name

User types the location name:
```
"Sportovní hala TJ Sokol"
"Fotbalové hřiště u ZŠ"
"Tělocvična Družba"
```

**Mapy.com suggestions still work** - autocomplete dropdown appears

### Step 3: Visual Verification

If coordinates imported:
- ✅ Map appears automatically
- ✅ Shows marker at exact location
- ✅ Marker uses club colors
- ✅ Displays event title + location
- ✅ Can verify correctness

### Step 4: Adjust if Needed

If location is wrong:
- Click "Zrušit souřadnice" button
- Try different map link
- Or just use location name without coordinates

---

## 📊 Location Options Comparison

| Method | Coordinates | Map Preview | Geocoding | Best For |
|--------|-------------|-------------|-----------|----------|
| **Import from URL** | ✅ Yes | ✅ Yes | Not needed | Precise locations |
| **Type location name** | ❌ No | ❌ No | ✅ Frontend* | Quick entry |
| **Mapy.com suggestions** | ❌ No | ❌ No | ✅ Frontend* | Popular places |

\* Frontend geocoding happens when event is displayed (EventLocationMap component)

---

## 🗺️ Map Preview Features

### Automatic Display
- Shows when lat/lng are set
- Uses club's map style setting
- Applies club primary color to marker
- Applies club accent color to elements

### Information Shown
- Event title (or location name)
- Location address
- Exact coordinates (lat, lng)
- Visual marker at location

### Controls
- "Zrušit souřadnice" button - clears lat/lng
- Coordinates remain until cleared
- Map updates if title/location changes

---

## 💡 Usage Recommendations

### For Precise Locations

1. **Find venue on Google Maps or Mapy.cz**
2. **Copy the URL**
3. **Paste into MapLinkImporter**
4. **Verify on preview map**
5. **Add location name** (will show to visitors)
6. **Save event**

**Example:**
```
Map URL: https://maps.google.com/...coords=50.0947,17.6997
→ Extracts: 50.0947, 17.6997
→ Map preview appears
→ Add name: "Fotbalové hřiště TJ Sokol Krnov"
→ Save
```

### For General Locations

1. **Type location name directly**
2. **Use Mapy.com suggestions if needed**
3. **Skip coordinates** (frontend will geocode)
4. **Save event**

**Example:**
```
Location: "Sportovní hala, Krnov"
→ No coordinates
→ No map preview
→ Frontend will geocode when displaying
→ Save
```

---

## 🎯 Benefits

### For Admins

1. **Visual Confirmation** - See exactly where event is
2. **Error Prevention** - Catch wrong locations before saving
3. **Professional Tools** - Same quality as Setup page
4. **Flexibility** - Can use coordinates OR just location name
5. **Club Branding** - Map uses club colors

### For Visitors

1. **Better Maps** - Precise coordinates when available
2. **Fallback Geocoding** - Works with just location name
3. **Consistent** - Same map style across site
4. **Club Colors** - Branded map markers

---

## 📝 Technical Details

### State Management

```typescript
// New state variables
const [locationLat, setLocationLat] = useState<number | undefined>(undefined);
const [locationLng, setLocationLng] = useState<number | undefined>(undefined);
```

### Map Preview Logic

```typescript
{locationLat && locationLng && (
  <ContactMap
    latitude={locationLat}
    longitude={locationLng}
    zoom={15}
    clubName={editing?.title || editing?.location}
    address={editing?.location}
    mapStyle={settingsQ.data?.map_style || 'positron'}
    clubPrimaryColor={settingsQ.data?.primary_color}
    clubSecondaryColor={settingsQ.data?.accent_color}
    height={300}
  />
)}
```

### Coordinate Import Handler

```typescript
onImport={(coords: MapCoordinates) => {
  setLocationLat(coords.latitude);
  setLocationLng(coords.longitude);
  toast({
    title: 'Souřadnice importovány',
    description: `Lat: ${coords.latitude.toFixed(6)}, Lng: ${coords.longitude.toFixed(6)}`,
    status: 'success',
  });
}}
```

---

## 🔄 Backward Compatibility

### Existing Events
- ✅ All existing events work unchanged
- ✅ Location field unchanged
- ✅ Mapy.com suggestions still work
- ✅ No data migration needed

### Frontend Display
- ✅ EventLocationMap component unchanged
- ✅ Still geocodes location names
- ✅ Works with or without coordinates
- ✅ Seamless experience

---

## 🆚 Comparison: Before vs After

### Before

**Location Input:**
```
[ Text Field: "Místo" ]
  └─ Mapy.com suggestions
```

**Features:**
- Basic text input
- Autocomplete suggestions
- No visual feedback
- No coordinates

### After

**Location Section:**
```
┌─ Místo konání ─────────────────┐
│                                 │
│ [MapLinkImporter]              │
│ ✓ Import from Google Maps       │
│ ✓ Import from Mapy.cz           │
│                                 │
│ [Název místa] [Typ]            │
│ ✓ Mapy.com suggestions          │
│                                 │
│ [Map Preview - 300px]          │
│ ✓ Visual verification           │
│ ✓ Club colors                   │
│ ✓ Coordinates display           │
│ ✓ Cancel button                 │
└─────────────────────────────────┘
```

**Features:**
- ✅ Professional map import tool
- ✅ Live visual preview
- ✅ Coordinate extraction
- ✅ Club color integration
- ✅ Easy verification
- ✅ Still backward compatible

---

## 🎬 User Flow Example

### Creating a Training Event

1. **Click "Nová aktivita"**
2. **Fill basic info:**
   - Title: "Trénink A-týmu"
   - Type: "Trénink"
   - Date/Time: Today 18:00

3. **Add location (NEW WAY):**
   - Go to Google Maps
   - Find "Fotbalové hřiště TJ Sokol"
   - Copy URL: `https://maps.google.com/...`
   - Paste in MapLinkImporter
   - Click "Importovat"
   - ✅ **Map appears showing exact location!**

4. **Add location name:**
   - Type: "Fotbalové hřiště TJ Sokol, Krnov"
   - (or select from Mapy.com suggestions)

5. **Verify on map:**
   - ✅ See marker at correct location
   - ✅ See club colors on marker
   - ✅ See coordinates

6. **Save**

**Result:** Event with precise coordinates AND user-friendly location name!

---

## 🎨 Visual Improvements

### Section Header
```
Místo konání
────────────
```
Clear heading separates location section

### MapLinkImporter Box
```
┌─────────────────────────────┐
│ Importovat z odkazu na mapu │
│                             │
│ [Paste link here...]        │
│ [Importovat] [Preview]      │
└─────────────────────────────┘
```
Highlighted box with gray background

### Map Preview
```
┌─────────────────────────────┐
│ Náhled polohy na mapě:      │
│ ┌─────────────────────────┐ │
│ │                         │ │
│ │    [Interactive Map]    │ │
│ │         300px           │ │
│ │                         │ │
│ └─────────────────────────┘ │
│                             │
│ Souřadnice: 50.094, 17.699  │
│ [Zrušit souřadnice]         │
└─────────────────────────────┘
```
Professional map preview with controls

---

## ✅ Testing Checklist

- [ ] Import from Google Maps link
- [ ] Import from Mapy.cz link
- [ ] Import from OpenStreetMap link
- [ ] Verify map preview appears
- [ ] Check club colors on marker
- [ ] Verify coordinates display
- [ ] Test "Zrušit souřadnice" button
- [ ] Type location manually (without import)
- [ ] Test Mapy.com suggestions still work
- [ ] Create event and save
- [ ] View event on frontend
- [ ] Verify map shows on event detail page

---

## 📚 Related Components

### Used Components
- `MapLinkImporter` - Extracts coordinates from map URLs
- `ContactMap` - Displays map with club colors
- `EventLocationMap` - Frontend display (unchanged)

### Files Modified
- `AdminActivitiesPage.tsx` - Enhanced location section

### Dependencies
- `mapUrlParser.ts` - URL parsing utility
- `getPublicSettings()` - For club colors/map style

---

## 🎯 Summary

The Activity Admin page now has:

✅ **Professional map tools** - Same quality as Setup page  
✅ **Visual verification** - See location before saving  
✅ **Club color integration** - Branded map previews  
✅ **Flexibility** - Coordinates OR location name  
✅ **Backward compatible** - All existing features work  
✅ **Better UX** - Clear, organized, helpful  

**Result:** Admins can create events with precise, verified locations and beautiful map previews! 🗺️✨

---

**Implementation Date:** 2025-10-10  
**Status:** ✅ Ready for Use  
**Complexity:** Medium  
**User Impact:** High (much better UX)