upload

DOCS/COUNTDOWN_IMPLEMENTATION.md

@@ -0,0 +1,93 @@
+# 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.