MyClub/DOCS/CLUB_LOGOS_MODAL_INTEGRATION.md

# Club Logos Modal Integration - Calendar & Homepage

## Overview
Integrated clickable club logos in the MatchModal (calendar/matches view) that open a ClubModal with team statistics, similar to the existing tabulky (standings) functionality.

## Changes Made

### 1. **MatchModal Component** (`frontend/src/components/home/MatchModal.tsx`)
- ✅ Added `onTeamClick` optional callback prop
- ✅ Made team logos clickable with hover effects
- ✅ Added visual feedback (opacity change and scale on hover)
- ✅ Accessible: cursor pointer, role button, tab navigation support

**New Interface:**
```typescript
interface MatchModalProps {
  isOpen: boolean;
  match: FacrMatchLike | null;
  onClose: () => void;
  onTeamClick?: (teamName: string, teamLogoUrl?: string) => void; // NEW
}
```

**Visual Changes:**
- Team logos now show pointer cursor on hover
- Scale up to 105% on hover
- Opacity reduces to 80% on hover
- Smooth transitions (0.2s)

### 2. **HomePage Component** (`frontend/src/pages/HomePage.tsx`)
- ✅ Added `handleTeamClickFromMatch` function
- ✅ Searches through standings data to find team statistics
- ✅ Falls back to minimal modal if team not found in standings
- ✅ Updated all MatchModal instances across different layout styles:
  - Magazine layout
  - Edge layout
  - PRO layout
  - Unified layout (default)

**Logic Flow:**
1. User clicks team logo in MatchModal
2. System normalizes team name for matching
3. Searches through all standings/competitions
4. If found: Shows full ClubModal with stats (wins, draws, losses, points, etc.)
5. If not found: Shows minimal ClubModal with just name and logo

**Team Name Normalization:**
- Removes diacritics (á → a, č → c, etc.)
- Converts to lowercase
- Trims whitespace
- Supports partial matching (handles prefixes like TJ, SK, MFK)

### 3. **CalendarPage Component** (`frontend/src/pages/CalendarPage.tsx`)
- ✅ Added ClubModal import
- ✅ Added state for ClubModal management
- ✅ Added standings data loading from FACR cache
- ✅ Implemented `handleTeamClick` function
- ✅ Made team logos clickable in the match detail modal
- ✅ Added ClubModal component at the end of the page

**New Features:**
- Loads standings from `/cache/prefetch/facr_tables.json`
- Processes team data (goals for/against, wins/draws/losses)
- Clickable team logos in calendar match modals
- Hover tooltips: "Klikněte pro zobrazení statistik: [Team Name]"

### 4. **ClubModal Component** (No Changes Required)
- Already exists with proper interface
- Displays team statistics beautifully
- Works for both football and futsal

## User Experience

### Before
- Team logos in match modals were static images
- No way to see team statistics from match view
- Had to navigate to standings page separately

### After
- Click home team logo → Opens ClubModal with team stats
- Click away team logo → Opens ClubModal with team stats
- Visual feedback on hover (scale + opacity)
- Seamless integration with existing standings data
- Works on both homepage and calendar page

## Technical Details

### Data Flow
```
MatchModal (team logo click)
    ↓
handleTeamClick(teamName, logoUrl)
    ↓
Search standings array
    ↓
Transform to ClubModal format
    ↓
Open ClubModal with team data
```

### Standings Data Structure
```typescript
{
  name: string,              // Competition name
  table: [{
    team_name: string,
    team_id: string,
    position: number,
    played: number,
    wins: number,
    draws: number,
    losses: number,
    goals_for: number,
    goals_against: number,
    points: number,
    logo_url?: string
  }]
}
```

### Team Matching Algorithm
1. Exact match: normalized names are identical
2. Contains match: one name contains the other
3. Fallback: Show minimal modal if no match found

## Files Modified

1. `frontend/src/components/home/MatchModal.tsx`
   - Added onTeamClick prop
   - Made logos clickable

2. `frontend/src/pages/HomePage.tsx`
   - Added handleTeamClickFromMatch function
   - Updated all 4 MatchModal instances
   - Added team search logic

3. `frontend/src/pages/CalendarPage.tsx`
   - Added ClubModal import
   - Added standings state and loading
   - Added handleTeamClick function
   - Made modal logos clickable
   - Added ClubModal component

## Testing Recommendations

### 1. **Homepage - All Layouts**
   - Test Magazine style
   - Test Edge style
   - Test PRO style
   - Test Unified style (default)

### 2. **Match Modal Interactions**
   - Click home team logo
   - Click away team logo
   - Verify ClubModal opens
   - Check hover effects work

### 3. **Calendar Page**
   - Open calendar view
   - Click match to open detail modal
   - Click team logos in modal
   - Verify statistics display correctly

### 4. **Team Matching**
   - Test with teams in standings → Full stats shown
   - Test with teams NOT in standings → Minimal modal shown
   - Test with Czech diacritics (Kravaře, Třinec, etc.)
   - Test with club prefixes (TJ, SK, MFK, Sokol)

### 5. **Edge Cases**
   - Teams with long names
   - Teams with special characters
   - Teams without logos
   - Empty standings data

## Browser Compatibility

- ✅ Modern browsers (Chrome, Firefox, Safari, Edge)
- ✅ Hover effects use standard CSS
- ✅ Transitions supported in all modern browsers
- ✅ Modal system uses Chakra UI (fully compatible)

## Performance Considerations

- Standings data loaded once on page mount
- Team search is O(n*m) but data is small (typically < 100 teams)
- No performance impact expected
- Modal rendering is lazy (only when opened)

## Future Enhancements

Potential improvements:
- Add team historical performance graph
- Show head-to-head statistics between teams
- Add recent form indicator (last 5 matches)
- Link to team detail page if available
- Cache team lookups for better performance

---

**Date:** 2025-10-11  
**Status:** ✅ Complete  
**Files Modified:** 3  
**New Components:** 0 (reused existing ClubModal)  
**Breaking Changes:** None