MyClub/DOCS/COUNTDOWN_IMPLEMENTATION.md

Countdown Timer Implementation

Summary

Countdown timers have been implemented for upcoming matches across all match displays in the application. When a match has not yet started, the system displays a live countdown showing the time remaining until kickoff.

Implementation Details

1. Match Modal (MatchModal.tsx)

Status: ✅ Already Implemented

The match modal shows:

• For upcoming matches: Countdown timer displaying "Začátek za [countdown]"
• For ongoing matches: Shows "—:—" with "Probíhá" status
• For finished matches: Shows the final score with "Skončeno" status

The countdown updates every second (1000ms) using the useCountdown hook.

2. Calendar Page (CalendarPage.tsx)

Status: ✅ Already Implemented

Countdowns appear in three places:

Calendar Grid View

• Each upcoming match displays an orange badge: "za [countdown]"
• Updates every 30 seconds for performance optimization
• Shows team logos alongside the countdown

List View

• Upcoming matches show countdown badge in orange
• Displays "za [countdown]" prominently
• Updates every 30 seconds

Calendar Modal

• When clicking a match, the modal shows countdown if the match hasn't started
• Updates every second for precision
• Format: "za [countdown]" in an orange badge

3. Matches Page (MatchesPage.tsx)

Status: ✅ NEWLY ADDED

Enhanced match cards to show countdown timers:

• Upcoming matches with countdown: Displays "Začátek za" with the countdown in orange (#f97316)
• Upcoming matches without countdown: Shows "Nadcházející" status
• Finished matches: Shows the score and "Skončeno" status
• Updates every 30 seconds using useMultipleCountdowns hook

4. Home Page (HomePage.tsx)

Status: ✅ Already Implemented

The homepage shows countdowns in multiple sections:

• Next Match Widget: Shows countdown for the next upcoming match
• Match Ticker: Displays countdown in various style modes (unified, magazine, pro, edge)
• Updates every second (1000ms) for real-time accuracy

Countdown Display Format

The countdown automatically adjusts based on time remaining:

• Days remaining: Xd Yh (e.g., "2d 5h")
• Hours remaining: Xh Ym (e.g., "5h 30m")
• Minutes remaining: Xm Ys (e.g., "45m 12s")
• Seconds remaining: Xs (e.g., "30s")

Technical Details

Hooks Used

1. useCountdown(targetDate, updateInterval)

   • Used for single match countdowns
   • Updates at specified interval (typically 1000ms for modals)
   • Returns: { countdownString, timeRemaining, isActive, targetTime }

2. useMultipleCountdowns(matches, updateInterval)

   • Used for tracking multiple matches simultaneously
   • Optimized for performance with longer intervals (30000ms)
   • Returns: Object mapping match IDs to countdown strings

Performance Optimization

• Calendar/Matches pages: Update every 30 seconds to minimize re-renders
• Modals/Homepage: Update every second for precision when viewing specific matches
• Countdowns automatically stop when time reaches zero

User Experience

When a match has not happened yet, users will see:

1. In Match Cards/Calendar: Orange countdown badge showing time until kickoff
2. In Modal: Prominent countdown display with "Začátek za" label
3. On Homepage: Real-time countdown in the next match section
4. Automatic Updates: Countdowns refresh automatically without user interaction

All countdown displays are localized in Czech and use consistent formatting across the application.