# Story 15.2: Potential Clients List with Type Filter

## Story

**As an** admin
**I want to** view a list of potential clients with filtering capabilities
**So that** I can easily browse and find specific prospective clients

## Acceptance Criteria

### AC1: Admin Navigation

**Given** the admin is logged in
**When** viewing the admin sidebar
**Then** a "Potential Clients" menu item is visible with an appropriate icon
**And** clicking it navigates to `/admin/potential-clients`

### AC2: List Page Header

**Given** the admin navigates to `/admin/potential-clients`
**When** the page loads
**Then** display:
- Page title: "Potential Clients" / "العملاء المحتملون"
- Subtitle: "Manage prospective clients" / "إدارة العملاء المحتملين"
- "Add Potential Client" button linking to create page

### AC3: Type Filter

**Given** the potential clients list
**When** the filter is displayed
**Then** a type dropdown includes:
- "All Types" (default) / "جميع الأنواع"
- "Individual" / "فرد"
- "Company" / "شركة"
- "Agency" / "وكالة"

**When** a type is selected
**Then** the list filters to show only potential clients of that type
**And** pagination resets to page 1

### AC4: Search Functionality

**Given** the potential clients list
**When** the admin types in the search box
**Then** filter potential clients by name, email, or phone
**And** search is debounced (300ms delay)
**And** pagination resets to page 1

### AC5: List Table Display

**Given** potential clients exist
**When** viewing the list
**Then** display a table with columns:
- Name (with avatar placeholder if no name)
- Type (with badge color per type)
- Email
- Phone
- Created date
- Actions (view, edit, delete icons)

### AC6: Type Badges

**Given** potential clients in the list
**When** displaying the type
**Then** show colored badges:
- Individual: Blue badge
- Company: Purple badge
- Agency: Amber badge

### AC7: Empty State

**Given** no potential clients exist
**When** viewing the list
**Then** display an empty state with:
- Icon (user-group or similar)
- Message: "No potential clients found" / "لم يتم العثور على عملاء محتملون"
- "Add Potential Client" button

**Given** filters are active but no results match
**When** viewing the list
**Then** display:
- Message: "No potential clients match your filters" / "لا يوجد عملاء محتملون يطابقون الفلاتر"
- "Clear filters" button

### AC8: Pagination

**Given** more than 10 potential clients exist
**When** viewing the list
**Then** display pagination controls
**And** allow changing items per page (10, 25, 50)

### AC9: Clear Filters

**Given** search or type filter is active
**When** admin clicks "Clear filters"
**Then** reset all filters to defaults
**And** show full unfiltered list

### AC10: RTL Support

**Given** Arabic language is selected
**When** viewing the potential clients list
**Then** all text and layout align correctly right-to-left

## Technical Notes

### Files to Create

| File | Purpose |
|------|---------|
| `resources/views/livewire/admin/potential-clients/index.blade.php` | List Volt component |
| `routes/web.php` | Add route for potential clients |

### Files to Modify

| File | Change |
|------|--------|
| `resources/views/components/layouts/admin/sidebar.blade.php` | Add navigation item |
| `lang/en/potential-clients.php` | Add list-related translations |
| `lang/ar/potential-clients.php` | Add list-related translations |

### Route Definition

```php
// In routes/web.php, within admin middleware group
Route::get('/admin/potential-clients', \App\Livewire\Admin\PotentialClients\Index::class)
    ->name('admin.potential-clients.index');
```

Or using Volt/Folio pattern based on existing structure.

### Component Structure

Follow the existing pattern from `admin/clients/individual/index.blade.php`:
- Use `WithPagination` trait
- Properties: `$search`, `$typeFilter`, `$perPage`
- Methods: `updatedSearch()`, `updatedTypeFilter()`, `updatedPerPage()`, `clearFilters()`
- `with()` method returning paginated query with filters

### Badge Colors by Type

```blade
@switch($potentialClient->type)
    @case(PotentialClientType::Individual)
        <flux:badge color="blue" size="sm">{{ $potentialClient->type->label() }}</flux:badge>
        @break
    @case(PotentialClientType::Company)
        <flux:badge color="purple" size="sm">{{ $potentialClient->type->label() }}</flux:badge>
        @break
    @case(PotentialClientType::Agency)
        <flux:badge color="amber" size="sm">{{ $potentialClient->type->label() }}</flux:badge>
        @break
@endswitch
```

### Additional Translations

```php
// Add to lang/en/potential-clients.php
'subtitle' => 'Manage prospective clients',
'add_potential_client' => 'Add Potential Client',
'all_types' => 'All Types',
'search_placeholder' => 'Search by name, email, or phone...',
'no_potential_clients_found' => 'No potential clients found',
'no_potential_clients_match' => 'No potential clients match your filters',
'clear_filters' => 'Clear filters',
'per_page' => 'per page',
'actions' => 'Actions',
'view' => 'View',
'edit' => 'Edit',
'delete' => 'Delete',
'created_at' => 'Created',

// Add to lang/ar/potential-clients.php
'subtitle' => 'إدارة العملاء المحتملين',
'add_potential_client' => 'إضافة عميل محتمل',
'all_types' => 'جميع الأنواع',
'search_placeholder' => 'البحث بالاسم أو البريد أو الهاتف...',
'no_potential_clients_found' => 'لم يتم العثور على عملاء محتملون',
'no_potential_clients_match' => 'لا يوجد عملاء محتملون يطابقون الفلاتر',
'clear_filters' => 'مسح الفلاتر',
'per_page' => 'لكل صفحة',
'actions' => 'الإجراءات',
'view' => 'عرض',
'edit' => 'تعديل',
'delete' => 'حذف',
'created_at' => 'تاريخ الإنشاء',
```

## Dev Checklist

- [x] Add route for potential clients index
- [x] Create Volt component `admin/potential-clients/index.blade.php`
- [x] Implement search functionality with debounce
- [x] Implement type filter dropdown
- [x] Implement pagination with per-page selector
- [x] Add navigation item to admin sidebar
- [x] Style type badges with correct colors
- [x] Handle empty state (no data)
- [x] Handle empty state (no filter matches)
- [x] Add English translations
- [x] Add Arabic translations
- [x] Test RTL layout
- [x] Write feature tests for list and filtering

## File List

### Created
- `resources/views/livewire/admin/potential-clients/index.blade.php` - Volt component for list page
- `tests/Feature/Admin/PotentialClientListTest.php` - Feature tests for list and filtering

### Modified
- `routes/web.php` - Added potential clients route
- `resources/views/components/layouts/app/sidebar.blade.php` - Added navigation item
- `lang/en/potential-clients.php` - Added list-related translations
- `lang/ar/potential-clients.php` - Added list-related translations
- `lang/en/navigation.php` - Added potential_clients key
- `lang/ar/navigation.php` - Added potential_clients key

## Status

Ready for Review

## Estimation

**Complexity:** Medium
**Risk:** Low - Follows established patterns

## Dependencies

- Story 15.1 (Database & Model) must be completed first
