# Pagination & Search - Quick Start Guide

## Overview

All admin list pages use consistent **server-side pagination** with search and filters.

**Pages using this pattern:**
- `/admin/vendors` - Vendor Management
- `/admin/companies` - Company Management
- `/admin/users` - User Management

---

## Visual Layout

```
┌──────────────────────────────────────────────────────────────────┐
│ Page Title                                    [+ Create Button]  │
├──────────────────────────────────────────────────────────────────┤
│ [Stat 1] [Stat 2] [Stat 3] [Stat 4]              ← Stats Cards   │
├──────────────────────────────────────────────────────────────────┤
│ [🔍 Search...    ] [Filter ▼] [Filter ▼] [Refresh] ← Search Bar  │
├──────────────────────────────────────────────────────────────────┤
│ Column 1 │ Column 2 │ Column 3 │ Actions                         │
├──────────┼──────────┼──────────┼─────────────────────────────────┤
│ Row 1    │ ...      │ ...      │ 👁 ✏️ 🗑                        │
│ Row 2    │ ...      │ ...      │ 👁 ✏️ 🗑                        │
│ ...      │ ...      │ ...      │ ...                             │
├──────────────────────────────────────────────────────────────────┤
│ Showing 1-10 of 45                  ← 1 2 [3] 4 ... 9 →          │
└──────────────────────────────────────────────────────────────────┘
```

---

## Key Features

| Feature | Description |
|---------|-------------|
| Server-side pagination | Uses `skip`/`limit` API params |
| Debounced search | 300ms delay before API call |
| Filter dropdowns | Status, Verification, Role filters |
| Smart page numbers | Shows ellipsis for large page ranges |
| Refresh button | Manually reload data |
| Contextual empty state | Different message when filters applied |

---

## State Structure

### JavaScript State
```javascript
// Filters
filters: {
    search: '',
    is_active: '',      // 'true', 'false', or ''
    is_verified: '',    // 'true', 'false', or ''
}

// Pagination
pagination: {
    page: 1,
    per_page: 10,
    total: 0,
    pages: 0
}
```

---

## Computed Properties

| Property | Purpose |
|----------|---------|
| `totalPages` | Total number of pages |
| `startIndex` | First item number on current page |
| `endIndex` | Last item number on current page |
| `pageNumbers` | Array of page numbers with '...' |

---

## Methods

| Method | Purpose |
|--------|---------|
| `debouncedSearch()` | Triggers search after 300ms |
| `previousPage()` | Go to previous page |
| `nextPage()` | Go to next page |
| `goToPage(num)` | Jump to specific page |

---

## Page Number Display

**Few pages (7 or less):**
```
← 1 2 3 4 5 6 7 →
```

**Many pages, at start:**
```
← [1] 2 3 ... 10 →
```

**Many pages, in middle:**
```
← 1 ... 4 [5] 6 ... 10 →
```

**Many pages, at end:**
```
← 1 ... 8 9 [10] →
```

---

## API Integration

### Request
```
GET /admin/vendors?skip=0&limit=10&search=acme&is_active=true
```

### Response
```json
{
    "vendors": [...],
    "total": 45,
    "skip": 0,
    "limit": 10
}
```

---

## Configuration

### Change Items Per Page

Edit in JavaScript file:
```javascript
pagination: {
    page: 1,
    per_page: 25,  // Change from 10
    total: 0,
    pages: 0
}
```

---

## Files Reference

| Page | Template | JavaScript |
|------|----------|------------|
| Vendors | `templates/admin/vendors.html` | `static/admin/js/vendors.js` |
| Companies | `templates/admin/companies.html` | `static/admin/js/companies.js` |
| Users | `templates/admin/users.html` | `static/admin/js/users.js` |

---

## Adding to a New Page

1. **Add state** to JavaScript:
```javascript
filters: { search: '', is_active: '' },
pagination: { page: 1, per_page: 10, total: 0, pages: 0 }
```

2. **Add computed properties**: `totalPages`, `startIndex`, `endIndex`, `pageNumbers`

3. **Add methods**: `debouncedSearch()`, `previousPage()`, `nextPage()`, `goToPage()`

4. **Update load function** to use query params

5. **Add HTML** for search bar and pagination footer

See `docs/frontend/shared/pagination.md` for full implementation details.