# Sports Activity Module — Smart Filtering & Search Plan

## المشكلة
الـ dropdowns في الموديل كله مفيش فيها filtering ذكي ولا search. لو اخترت نشاط رياضي معين، المجموعات والمدربين مش بيتفلترو. ولو عندي 500+ لاعب في dropdown مقدرش أدور فيها.

---

## الحل: مكونين أساسيين

### 1. Searchable Select Component
كل dropdown فيها أكتر من 10 عناصر أو فيها أسماء (لاعبين/مدربين) لازم تبقى searchable. هنعمل component واحد `searchable-select` يشتغل بـ vanilla JS.

### 2. Cascading/Dependent Filtering
لو اخترت parent field، الـ child fields لازم تتفلتر. ده موجود جزئياً في Groups create فقط، محتاج يتعمم.

---

## Edge Cases بالتفصيل (حسب الشاشة)

---

### A. Groups (المجموعات) — `Views/groups/`

| # | الشاشة | الحقل | المشكلة | الحل |
|---|--------|-------|---------|------|
| A1 | create/edit | `program_id` | ✅ بيتفلتر من discipline (موجود) | لا يحتاج تغيير |
| A2 | create/edit | `coach_id` | ✅ بيتفلتر من discipline (موجود) | لا يحتاج تغيير — بس محتاج يبقى searchable |
| A3 | show (enrolled players) | عرض اللاعبين | لو المجموعة فيها 50+ لاعب مفيش search | إضافة filter/search في الجدول |
| A4 | show (add player) | `player_id` dropdown | بيجيب كل اللاعبين الغير مسجلين في المجموعة دي — لو 1000 لاعب الdropdown بطيئة | **Searchable select + AJAX search** بدل ما يجيبهم كلهم |
| A5 | index (filters) | `program_id` filter | مفيش فلتر بالنشاط الرياضي — لازم discipline → program cascading | إضافة discipline filter + cascading |
| A6 | index (filters) | `coach_id` filter | مفيش فلتر بالمدرب | إضافة coach filter (searchable) |

---

### B. Subscriptions (الاشتراكات) — `Views/subscriptions/`

| # | الشاشة | الحقل | المشكلة | الحل |
|---|--------|-------|---------|------|
| B1 | index | `group_id` filter | بيجيب كل المجموعات بدون cascading من النشاط | إضافة discipline filter قبلها + cascading |
| B2 | index | لاعب معين | مفيش search بالاسم أو الرقم القومي | إضافة search field |

---

### C. Bookings Wizard (معالج الحجز) — `Views/bookings/wizard.php`

| # | الشاشة | الحقل | المشكلة | الحل |
|---|--------|-------|---------|------|
| C1 | Step 2 | Unit selection | الوحدات مجمعة بالمرفق ✅ بس لو كتير مفيش search | Searchable select |
| C2 | Step 2 | Facility filter | مفيش فلتر بنوع المرفق (ملعب/حمام سباحة/صالة) | إضافة type filter chips |

---

### D. Bookings Create (إنشاء حجز بسيط) — `Views/bookings/create.php`

| # | الشاشة | الحقل | المشكلة | الحل |
|---|--------|-------|---------|------|
| D1 | create | `facility_unit_id` | بيجيب كل الوحدات في optgroup — لو 30+ وحدة صعب تلاقي | Searchable select |

---

### E. Locker Rentals (تأجير اللوكرز) — `Views/locker-rentals/create.php`

| # | الشاشة | الحقل | المشكلة | الحل |
|---|--------|-------|---------|------|
| E1 | create | `player_id` | **بيجيب كل اللاعبين** — أكبر مشكلة! | **AJAX searchable select** (بالاسم/الرقم القومي/السيريال) |
| E2 | create | `locker_id` | بيعرض اللوكرز المتاحة بس — ممكن تكون كتير | Searchable + فلتر بالمرفق |

---

### F. Registration Wizard (معالج التسجيل) — `Views/registration/wizard.php`

| # | الشاشة | الحقل | المشكلة | الحل |
|---|--------|-------|---------|------|
| F1 | Activity step | Group selection | ✅ فيه client-side search (data-name) | كافي — بس لو المجموعات > 50 يحتاج server-side |
| F2 | Activity step | مفيش discipline filter | اللاعب بيشوف كل المجموعات بدون فلتر بالنشاط | إضافة discipline tabs/chips قبل المجموعات |
| F3 | Activity step | مفيش program filter | بعد اختيار النشاط مفيش فلتر بالبرنامج | إضافة program sub-filter |

---

### G. Coaches (المدربين) — `Views/coaches/`

| # | الشاشة | الحقل | المشكلة | الحل |
|---|--------|-------|---------|------|
| G1 | create/edit | `discipline_ids[]` | القائمة قصيرة عادةً | لا يحتاج تغيير |
| G2 | create/edit | `academy_id` | بيظهر بس لو coach_type=academy ✅ | لا يحتاج — بس لو الأكاديميات كتير يبقى searchable |
| G3 | index | مفيش فلتر بالنشاط الرياضي | المدربين بيتعرضو كلهم | إضافة discipline filter |

---

### H. Players (اللاعبين) — `Views/players/`

| # | الشاشة | الحقل | المشكلة | الحل |
|---|--------|-------|---------|------|
| H1 | index | مفيش فلتر بالنشاط/المجموعة | بيعرض كل اللاعبين | إضافة discipline + group filters |
| H2 | index | Search | ✅ موجود (اسم/رقم قومي/سيريال) | كافي |

---

### I. Attendance (الحضور) — `Views/attendance/`

| # | الشاشة | الحقل | المشكلة | الحل |
|---|--------|-------|---------|------|
| I1 | index | مفيش اختيار مجموعة/مدرب/نشاط | بيعرض كل جدول اليوم | إضافة discipline + coach filter |

---

### J. Facilities (المرافق) — `Views/facilities/`

| # | الشاشة | الحقل | المشكلة | الحل |
|---|--------|-------|---------|------|
| J1 | create/edit | `discipline_id` | dropdown عادي — غالباً قصير | لا يحتاج searchable |
| J2 | index | `type` filter | ✅ موجود | كافي |

---

### K. Programs (البرامج) — `Views/programs/`

| # | الشاشة | الحقل | المشكلة | الحل |
|---|--------|-------|---------|------|
| K1 | index | `discipline_id` filter | ✅ موجود | كافي |
| K2 | create/edit | `discipline_id` | dropdown عادي — قصير | لا يحتاج |
| K3 | create/edit | `academy_id` | لو الأكاديميات > 10 محتاج search | Searchable إذا لزم |

---

### L. Pool Grid — `Views/pool-grid/`

| # | الشاشة | الحقل | المشكلة | الحل |
|---|--------|-------|---------|------|
| L1 | manage | Player assignment | لو بيختار لاعب لـ zone يحتاج search | AJAX player search |

---

### M. Mirror (المرآة) — `Views/mirror/`

| # | الشاشة | الحقل | المشكلة | الحل |
|---|--------|-------|---------|------|
| M1 | index | Discipline filter | ✅ موجود (chips) | كافي |

---

### N. Service Desk — `Views/service-desk/`

| # | الشاشة | الحقل | المشكلة | الحل |
|---|--------|-------|---------|------|
| N1 | index | Player lookup | ✅ NID-based lookup | كافي |

---

## ملخص الأولويات

### 🔴 Critical (مطلوب فوراً — UX مكسور)

| # | المكان | المشكلة |
|---|--------|---------|
| **E1** | Locker Rentals → player_id | كل اللاعبين في dropdown واحد بدون search |
| **A4** | Group Show → add player | كل اللاعبين المتاحين بدون search |
| **L1** | Pool Grid → player assignment | اختيار لاعب بدون search |

### 🟠 High Priority (Cascading مفقود)

| # | المكان | المشكلة |
|---|--------|---------|
| **A5** | Groups Index | مفيش فلتر discipline → program cascading |
| **B1** | Subscriptions Index | group filter بدون discipline parent |
| **F2** | Registration Wizard | المجموعات بدون فلتر بالنشاط |
| **H1** | Players Index | مفيش فلتر بالنشاط/المجموعة |
| **G3** | Coaches Index | مفيش فلتر بالنشاط |
| **I1** | Attendance | مفيش فلتر بالنشاط/المدرب |

### 🟡 Medium (Search مطلوب لـ UX أحسن)

| # | المكان | المشكلة |
|---|--------|---------|
| **A2** | Groups create/edit → coach_id | searchable مطلوب لو المدربين > 10 |
| **C1** | Booking Wizard → unit | searchable لو الوحدات كتير |
| **D1** | Booking Create → facility_unit_id | searchable |
| **E2** | Locker Rentals → locker_id | searchable + facility filter |
| **B2** | Subscriptions Index | search بالاسم/الرقم القومي |
| **A6** | Groups Index | coach filter (searchable) |

### 🟢 Low (Nice to have)

| # | المكان | المشكلة |
|---|--------|---------|
| **C2** | Booking Wizard | type filter chips |
| **F3** | Registration Wizard | program sub-filter |
| **K3** | Programs create/edit → academy_id | searchable لو كتير |
| **G2** | Coaches create/edit → academy_id | searchable لو كتير |

---

## التنفيذ التقني

### Step 1: Searchable Select Component (`public/assets/js/searchable-select.js`)
- Vanilla JS component يحول أي `<select>` لـ searchable dropdown
- يشتغل بـ attribute: `data-searchable="true"`
- يدعم AJAX loading: `data-search-url="/api/sa/players/search"` + `data-search-min="2"`
- يدعم grouping (optgroup)
- RTL compatible
- Keyboard navigation

### Step 2: API Endpoints المطلوبة
```
GET /api/sa/players/search?q={query}&discipline_id={id}&group_id={id}
GET /api/sa/groups/search?q={query}&discipline_id={id}&program_id={id}
GET /api/sa/coaches/search?q={query}&discipline_id={id}
```

### Step 3: Enhanced Cascading via `forms-engine.js`
- توسيع `data-depends-on` ليدعم multiple parents
- إضافة `data-cascade-reset="true"` — يفرغ الحقل لما الparent يتغير
- إضافة `data-cascade-disable="true"` — يعطل الحقل لحد ما الparent يتملى

### Step 4: Filter Enhancement per Page
- إضافة discipline filter في كل index page مفيهوش
- ربط cascading بين discipline → program → group في كل الصفحات

---

## ملاحظات
- الـ `forms-engine.js` الموجود فيه `data-depends-on` بس مستخدم بشكل محدود
- الـ `PlayerSearchApiController` موجود فعلاً ويرجع نتائج — محتاج بس يتربط بالـ UI
- Groups create/edit عنده cascading discipline→programs/coaches — ده الpattern المطلوب يتعمم
