MyClub/DOCS/MAP_LINK_IMPORT_FEATURE.md

# Map Link Import Feature

## Overview
This feature allows administrators to easily import map coordinates from popular map services (mapy.cz and Google Maps) by simply pasting a URL. The system automatically extracts coordinates and displays a live preview of the location.

## Implementation Summary

### 1. URL Parser Utility (`src/utils/mapUrlParser.ts`)
**Purpose**: Parse map URLs from various sources and extract coordinates

**Features**:
- Supports **mapy.cz** URLs (mapy.com/mapy.cz domains)
- Supports **Google Maps** URLs (various formats)
- Automatic protocol detection and normalization
- Coordinate validation
- Extracts: latitude, longitude, zoom level, and location name (when available)

**Supported URL Formats**:
- **mapy.cz**: `mapy.com/en/letecka?x=17.6996859&y=50.0947150&z=19`
- **Google Maps**: 
  - `google.com/maps/place/@50.0946232,17.6987331,226m`
  - `google.com/maps/@lat,lng,zoom`
  - `google.com/maps?q=lat,lng`

**Example Usage**:
```typescript
import { parseMapUrl } from './utils/mapUrlParser';

const result = parseMapUrl('mapy.com/en/letecka?x=17.6996859&y=50.0947150&z=19');
// Returns: {
//   latitude: 50.0947150,
//   longitude: 17.6996859,
//   zoom: 19,
//   address: 'krnov stadion',
//   source: 'mapy.cz'
// }
```

### 2. MapLinkImporter Component (`src/components/admin/MapLinkImporter.tsx`)
**Purpose**: React component for importing map coordinates with live preview

**Features**:
- URL input field with real-time parsing
- Automatic recognition of map service (mapy.cz/Google Maps)
- Visual feedback with success/error messages
- Live map preview using existing ContactMap component
- Shows parsed coordinates, zoom level, and location name
- Import button to apply coordinates to settings
- Manual coordinate override support

**Props**:
```typescript
interface MapLinkImporterProps {
  onImport: (coordinates: MapCoordinates) => void;
  currentLatitude?: number;
  currentLongitude?: number;
  currentZoom?: number;
}
```

### 3. Settings Admin Page Integration (`src/pages/admin/SettingsAdminPage.tsx`)
**Purpose**: New "Kontakt & Mapa" tab in admin settings

**Added Features**:
- New tab: "Kontakt & Mapa" between "Sociální sítě" and "Videa"
- Contact information fields:
  - Address (street)
  - City
  - Postal code
  - Country
  - Phone
  - Email
- Map coordinate import section with MapLinkImporter component
- Manual coordinate input (latitude, longitude, zoom)
- Map display toggle for homepage
- Map style selection (Default/Dark/Satellite)

### 4. Updated Type Definitions (`src/services/settings.ts`)
**New AdminSettings Fields**:
```typescript
{
  contact_address?: string;
  contact_city?: string;
  contact_zip?: string;
  contact_country?: string;
  contact_phone?: string;
  contact_email?: string;
  location_latitude?: number;
  location_longitude?: number;
  map_zoom_level?: number;
  show_map_on_homepage?: boolean;
  map_style?: 'default' | 'dark' | 'satellite';
}
```

## Usage Instructions

### For Administrators:

1. **Navigate to Settings**:
   - Go to Admin Panel → Settings
   - Click on "Kontakt & Mapa" tab

2. **Import from Map URL**:
   - Copy a URL from mapy.cz or Google Maps
   - Paste it into the "Importovat z URL mapy" field
   - The system will automatically:
     - Parse the coordinates
     - Display the location details
     - Show a live map preview
   - Click "Importovat" to apply the coordinates

3. **Manual Entry** (Alternative):
   - Scroll to "Ruční nastavení souřadnic"
   - Enter latitude, longitude, and zoom level manually

4. **Configure Display**:
   - Toggle "Zobrazit mapu na titulní stránce" to show/hide map on homepage
   - Select map style (Default, Dark, or Satellite)

5. **Save Settings**:
   - Click "Uložit nastavení" at the bottom of the page

### Example URLs to Test:

**mapy.cz**:
```
mapy.com/en/letecka?q=krnov%20stadion&source=firm&id=12954454&ds=2&x=17.6996859&y=50.0947150&z=19
```

**Google Maps**:
```
www.google.com/maps/place/Fotbalový+stadión/@50.0946232,17.6987331,226m/data=!3m1!1e3!4m10!1m2!2m1!1skrnov+stadion!3m6!1s0x4711826a3559a643:0x4d71cca773c76501!8m2!3d50.0948669!4d17.7001456
```

## Technical Details

### Files Created:
1. `src/utils/mapUrlParser.ts` - URL parsing utility
2. `src/utils/mapUrlParser.test.ts` - Test suite
3. `src/components/admin/MapLinkImporter.tsx` - Import component

### Files Modified:
1. `src/pages/admin/SettingsAdminPage.tsx` - Added new tab and integration
2. `src/services/settings.ts` - Extended AdminSettings type

## Testing

### Running Tests:
```bash
npm test -- mapUrlParser.test.ts
```

### Manual Testing:
1. Navigate to `/admin/settings`
2. Go to "Kontakt & Mapa" tab
3. Paste one of the example URLs
4. Verify the coordinates are correctly extracted
5. Check that the map preview displays correctly
6. Click "Importovat" and verify coordinates are applied
7. Save settings and verify they persist

## Benefits

✅ **User-Friendly**: No need to manually find coordinates
✅ **Accurate**: Directly extracts coordinates from map URLs
✅ **Visual Feedback**: Live map preview before importing
✅ **Flexible**: Supports multiple map services
✅ **Robust**: Validates coordinates and handles errors
✅ **Integrated**: Works seamlessly with existing ContactMap component

## Future Enhancements (Optional)

- Add support for more map services (OpenStreetMap, Bing Maps, etc.)
- Geocoding: Convert address to coordinates automatically
- Reverse geocoding: Auto-fill address from coordinates
- Map marker drag-and-drop for coordinate selection
- Batch import for multiple locations

## Backend Requirements

The backend should support the following fields in the settings model:
- `contact_address` (string)
- `contact_city` (string)
- `contact_zip` (string)
- `contact_country` (string)
- `contact_phone` (string)
- `contact_email` (string)
- `location_latitude` (float/double)
- `location_longitude` (float/double)
- `map_zoom_level` (integer)
- `show_map_on_homepage` (boolean)
- `map_style` (enum: 'default', 'dark', 'satellite')

These should be added to the existing settings table/model.