# 🎂 Widget Urodziny Zawodników

> **Wersja:** 1.3.0  
> **Data:** 2026-01-14

## 🎯 Przegląd

**Sonics Birthday Widget** to widget WordPress wyświetlający zawodników, którzy mają urodziny **dzisiaj** lub w **najbliższych dniach**. Widget posiada:

- 🎉 Specjalną animację dla urodzin dzisiejszych
- ⏱️ Odliczanie do urodzin
- 📅 Wyświetlanie wieku
- 🔗 Linki do stron zawodników (CPT)
- 🎨 Stylizację w kolorach Seattle SuperSonics

---

## 🚀 Jak używać

### Dodawanie widgetu

1. Przejdź do **Wygląd → Widgety** w panelu WordPress
2. Znajdź widget **"Sonics - Urodziny zawodników"**
3. Przeciągnij do wybranego obszaru sidebaru (np. "Main Sidebar")
4. Skonfiguruj ustawienia:
   - **Tytuł:** np. "Urodziny zawodników" lub "🎂 Dzisiaj obchodzi urodziny"
   - **Dni do przodu:** liczba dni (np. 7 = tydzień, 30 = miesiąc)
   - **Wyświetl wiek:** zaznacz aby pokazać ile lat ukończy zawodnik
   - **Wyświetl odliczanie:** zaznacz aby pokazać countdown do urodzin
5. Kliknij **Zapisz**

Widget pojawi się w sidebarze na froncie strony.

---

## 🎨 Wygląd widgetu

### Urodziny dzisiaj
```
🎂 Urodziny zawodników
┌────────────────────────────────────┐
│ [ZDJĘCIE]  Gary Payton             │
│            🎉 Dziś! (23.07)        │
│            Ukończy 56 lat          │
│                                    │
│            [Pulsująca animacja]    │
└────────────────────────────────────┘
```

Zawodnik z urodzinami dzisiaj ma:
- Zielone tło z gradientem (#00A651 → #2D5C2D)
- Złotą ramkę (#FFC72C)
- Pulsującą animację
- Emoji 🎉 + tekst "Dziś!"

### Nadchodzące urodziny
```
┌────────────────────────────────────┐
│ [ZDJĘCIE]  Shawn Kemp              │
│            Za 3 dni (26.11)        │
│            Ukończy 54 lata         │
│            ⏱️ Odliczanie: 3 dni    │
└────────────────────────────────────┘
```

Nadchodzące urodziny mają:
- Jasne tło (#f8f9fa)
- Zieloną lewą ramkę
- Countdown do urodzin

---

## ⚙️ Opcje konfiguracji

### Tytuł
**Domyślnie:** "Urodziny zawodników"

Przykłady:
- "🎂 Urodziny"
- "Dzisiaj obchodzi urodziny"
- "Nadchodzące urodziny"
- "Birthday Alert!"

### Dni do przodu
**Domyślnie:** 7 (tydzień)

Zakres: 1-365 dni

Przykłady:
- **7 dni** - najbliższy tydzień
- **14 dni** - 2 tygodnie
- **30 dni** - miesiąc
- **90 dni** - kwartał

### Wyświetl wiek
**Domyślnie:** Zaznaczone

Gdy zaznaczone, wyświetla:
```
Ukończy 56 lat
```

Odmiana:
- 1 rok
- 2-4 lata
- 5+ lat

### Wyświetl odliczanie
**Domyślnie:** Zaznaczone

Gdy zaznaczone, wyświetla countdown:
```
⏱️ Odliczanie: 5 dni
```

Tylko dla przyszłych urodzin (nie dla "Dziś!").

---

## 🛠️ Techniczne szczegóły

### Klasa `Sonics_Birthday_Widget`

Lokalizacja: `includes/class-sonics-birthday-widget.php`

Dziedziczy z `WP_Widget`.

#### Metody

**`widget( $args, $instance )`**
- Renderuje widget na froncie
- Pobiera nadchodzące urodziny z bazy
- Wyświetla listę zawodników

**`form( $instance )`**
- Formularz konfiguracji w panelu admin
- 4 pola: tytuł, dni do przodu, checkbox wiek, checkbox countdown

**`update( $new_instance, $old_instance )`**
- Zapisuje ustawienia widgetu
- Sanitizacja danych

**`get_upcoming_birthdays( $days_ahead )`**
- Zapytanie SQL do bazy
- Zwraca zawodników z urodzinami w najbliższych X dniach
- Sortowanie po liczbie dni do urodzin

**`get_player_post_id( $player_id )`**
- Znajduje ID posta CPT dla zawodnika
- Używa `WP_Query` z `meta_query`

**`render_birthday_item( $birthday, $show_age, $show_countdown )`**
- Renderuje pojedynczy element listy
- Obsługuje zdjęcie, nazwę, datę, wiek, countdown

---

## 🗄️ Zapytanie SQL

Widget używa zaawansowanego zapytania SQL do znalezienia urodzin:

```sql
SELECT 
    p.id,
    p.name,
    p.birth_date,
    p.photo_url,
    YEAR(CURDATE()) - YEAR(p.birth_date) AS age,
    DATEDIFF(
        DATE_ADD(
            p.birth_date, 
            INTERVAL YEAR(CURDATE()) - YEAR(p.birth_date) YEAR
        ),
        CURDATE()
    ) AS days_until
FROM wp_sonics_players p
WHERE p.birth_date IS NOT NULL
AND p.birth_date != '0000-00-00'
AND DATEDIFF(
    DATE_ADD(
        p.birth_date, 
        INTERVAL YEAR(CURDATE()) - YEAR(p.birth_date) YEAR
    ),
    CURDATE()
) BETWEEN 0 AND 7
ORDER BY days_until ASC, p.name ASC
```

**Jak to działa:**
1. Przesuwa datę urodzenia na bieżący rok
2. Oblicza różnicę w dniach od dzisiaj
3. Filtruje tylko urodziny w zakresie 0-X dni
4. Sortuje po liczbie dni (najbliższe pierwsze)

---

## 🎨 Style CSS

Lokalizacja: `assets/css/public-style.css`

### Główne klasy

**`.sonics-birthday-widget`**
- Kontener widgetu
- Białe tło, zaokrąglone rogi

**`.sonics-birthday-item`**
- Pojedynczy zawodnik
- Flexbox layout (zdjęcie + info)
- Hover effect - przesunięcie w prawo
- Border-left w kolorze zespołu

**`.sonics-birthday-item.is-today`**
- Specjalna klasa dla urodzin dzisiejszych
- Gradient zielony (#00A651 → #2D5C2D)
- Biały tekst
- Pulsująca animacja

**`.birthday-photo img`**
- Okrągłe zdjęcie (60px × 60px)
- Border w kolorze zespołu
- Złoty border dla urodzin dzisiejszych

**`.birthday-countdown`**
- Pill-shaped badge
- Zielone tło (rgba)
- Bold tekst

### Animacja pulsowania

```css
@keyframes birthdayPulse {
    0%, 100% {
        box-shadow: 0 0 10px rgba(255, 199, 44, 0.5);
    }
    50% {
        box-shadow: 0 0 20px rgba(255, 199, 44, 0.8);
    }
}
```

Pulsuje złotym cieniem (#FFC72C) dla urodzin dzisiejszych.

---

## 📱 Responsywność

Widget jest w pełni responsywny:

**Desktop:**
- Pełny layout ze zdjęciami (60px)
- Wszystkie informacje widoczne

**Mobile (< 768px):**
- Zmniejszone paddingi (10px)
- Responsywna czcionka
- Zdjęcia zachowują rozmiar

---

## 🔍 Przykłady użycia

### Sidebar
Najczęściej używany w sidbarze:
```
Main Sidebar
├── Search
├── Recent Posts
├── Sonics - Urodziny zawodników ← tutaj
└── Categories
```

### Shortcode (custom)
Widget można również wywołać programatically:

```php
the_widget( 'Sonics_Birthday_Widget', array(
    'title'      => 'Urodziny tego tygodnia',
    'days_ahead' => 7,
    'show_age'   => true,
    'show_countdown' => true,
) );
```

### Template file
W pliku templatki:

```php
<?php if ( is_active_widget( false, false, 'sonics_birthday_widget' ) ) : ?>
    <div class="birthday-section">
        <?php dynamic_sidebar( 'sidebar-1' ); ?>
    </div>
<?php endif; ?>
```

---

## 🎯 Use Cases

### 1. Sidebar "Dzisiaj"
```
Tytuł: "🎉 Dzisiaj obchodzi urodziny"
Dni: 0 (tylko dzisiaj)
Wiek: TAK
Countdown: NIE
```

### 2. Widget "Ten tydzień"
```
Tytuł: "Urodziny w tym tygodniu"
Dni: 7
Wiek: TAK
Countdown: TAK
```

### 3. Widget "Ten miesiąc"
```
Tytuł: "Nadchodzące urodziny"
Dni: 30
Wiek: NIE
Countdown: TAK
```

---

## 🐛 Troubleshooting

### Widget nie wyświetla się

**Przyczyny:**
1. Brak zawodników z urodzinami w wybranym zakresie dni
2. Brak daty urodzenia w bazie (pole `birth_date` puste)
3. Widget nie dodany do sidebaru

**Rozwiązanie:**
1. Zwiększ "Dni do przodu"
2. Sprawdź czy zawodnicy mają wypełnione pole `birth_date`
3. Dodaj widget do aktywnego sidebaru

### Brak zdjęć

Zdjęcia zawodników pobierane są z pola `photo_url` w tabeli `wp_sonics_players`.

**Rozwiązanie:**
- Dodaj URL zdjęcia w panelu "Zawodnicy"
- Import z Basketball Reference (obecnie BR nie udostępnia zdjęć w HTML)

### Zły format daty

Widget wymaga formatu `YYYY-MM-DD` w polu `birth_date`.

Przykłady poprawne:
- `1968-07-23` ✅
- `1972-11-26` ✅

Niepoprawne:
- `07/23/1968` ❌
- `23-07-1968` ❌
- `0000-00-00` ❌

---

## 🎨 Customizacja

### Zmiana kolorów

Edytuj `assets/css/public-style.css`:

```css
/* Kolor główny widgetu */
.sonics-birthday-item {
    border-left-color: #YOUR_COLOR; /* Zamiast #00A651 */
}

/* Kolor urodzin dzisiejszych */
.sonics-birthday-item.is-today {
    background: linear-gradient(135deg, #YOUR_COLOR1 0%, #YOUR_COLOR2 100%);
    border-left-color: #YOUR_ACCENT;
}

/* Kolor linków */
.birthday-name a:hover {
    color: #YOUR_COLOR;
}
```

### Zmiana rozmiaru zdjęć

```css
.birthday-photo img {
    width: 80px;  /* Zamiast 60px */
    height: 80px;
}
```

### Ukrycie countdownu

Jeśli chcesz trwale ukryć countdown:

```css
.birthday-countdown {
    display: none !important;
}
```

---

## 📋 Checklist implementacji

- [x] Klasa widgetu `Sonics_Birthday_Widget`
- [x] Rejestracja widgetu `register_widget()`
- [x] Formularz konfiguracji w admin
- [x] Zapytanie SQL do bazy
- [x] Integracja z CPT (linki do stron)
- [x] Style CSS z animacjami
- [x] Responsywność mobile
- [x] Obsługa zdjęć zawodników
- [x] Countdown i wiek
- [x] Emoji i ikony
- [x] Dokumentacja

---

## 🚀 Przyszłe rozszerzenia

- [ ] **Widget Dashboard** - widget w panelu admin WordPress
- [ ] **Email notifications** - wysyłanie maili o urodzinach
- [ ] **Birthday calendar** - kalendarz z urodzinami
- [ ] **Social media posts** - automatyczne posty na FB/Twitter
- [ ] **Customizer support** - konfiguracja kolorów w Customizer
- [ ] **Translations** - wielojęzyczność
- [ ] **Cache** - cache dla zapytań SQL (Transient API)

---

## 📞 Przykład

Zobacz widget w akcji:

1. Dodaj testowego zawodnika z urodzinami dzisiaj:
```sql
UPDATE wp_sonics_players 
SET birth_date = CURDATE() - INTERVAL 30 YEAR
WHERE id = 1;
```

2. Dodaj widget do sidebaru
3. Odśwież stronę
4. Zobaczysz pulsującą kartę z 🎉

---

## 📝 Notatki

- Widget automatycznie ukrywa się gdy brak urodzin w wybranym zakresie
- Sortowanie: najbliższe urodziny na górze
- Wiele zawodników tego samego dnia - wszyscy wyświetleni
- Widget działa zarówno w sidebarze jak i w blokach Gutenberg (jako "Widget Legacy")