npm package: @libs-ui/components-pagination
Description: > Component phân trang (Pagination) mạnh mẽ, hỗ trợ điều hướng nhanh, nhảy trang và hiển thị linh hoạt.
Latest version: 0.2.356-23

# @libs-ui/components-pagination

> Component phân trang (Pagination) mạnh mẽ, hỗ trợ điều hướng nhanh, nhảy trang và hiển thị linh hoạt.

## Giới thiệu

`LibsUiComponentsPaginationComponent` là một standalone Angular component giúp chia nhỏ dữ liệu thành các trang, cung cấp trải nghiệm điều hướng mượt mà cho các bảng dữ liệu hoặc danh sách lớn.

### Tính năng

- ✅ **Hiển thị linh hoạt**: Hỗ trợ hiển thị tổng số trang và ô nhập nhảy trang (Go to page).
- ✅ **Layout tùy biến**: Vùng thông tin bổ trợ có thể đặt ở 4 hướng (Top, Bottom, Left, Right).
- ✅ **Debounced Input**: Tránh việc nhảy trang liên tục khi người dùng đang nhập số trang thủ công.
- ✅ **Auto-Recalculation**: Tự động tính toán lại danh sách trang hiển thị khi số lượng item hoặc trang hiện tại thay đổi.
- ✅ **Angular Signals**: Sử dụng hoàn toàn Signals để quản lý trạng thái hiệu quả.

## Khi nào sử dụng

- Khi hiển thị danh sách dữ liệu lớn (Table, Grid, List) cần phân chia theo trang.
- Khi cần cung cấp cho người dùng khả năng nhảy nhanh đến một trang cụ thể bằng cách nhập số.
- Phù hợp cho cả ứng dụng desktop và web dashboard.

## Cài đặt

```bash
# npm
npm install @libs-ui/components-pagination

# yarn
yarn add @libs-ui/components-pagination
```

## Import

```typescript
import { LibsUiComponentsPaginationComponent } from '@libs-ui/components-pagination';

@Component({
  standalone: true,
  imports: [LibsUiComponentsPaginationComponent],
  // ...
})
export class YourComponent {}
```

## Ví dụ

### Basic

```html
<libs_ui-components-pagination
  [totalItems]="100"
  [perPage]="10"
  [(currentPage)]="currentPage"
  (outPageSelect)="onPageChange($event)" />
```

### Advanced (Show goto & total)

```html
<libs_ui-components-pagination
  [totalItems]="500"
  [perPage]="20"
  [(currentPage)]="currentPage"
  [showTotalPage]="true"
  [showInputGotoPage]="true"
  [modeDisplayTotalPageAndGotoPage]="'right'" />
```

## API

### libs_ui-components-pagination

#### Inputs

| Property                             | Type                                     | Default      | Description                                                     |
| ------------------------------------ | ---------------------------------------- | ------------ | --------------------------------------------------------------- |
| `[classIncludeContainer]`            | `string`                                 | `undefined`  | Custom class cho container chính.                               |
| `[classIncludeItem]`                 | `string`                                 | `undefined`  | Custom class cho từng nút phân trang.                           |
| `[classDisplayTotalPageAndGotoPage]` | `string`                                 | `undefined`  | Custom class cho vùng tổng trang & nhảy trang.                  |
| `[disable]`                          | `boolean`                                | `false`      | Vô hiệu hóa tương tác phân trang.                               |
| `[modeDisplayTotalPageAndGotoPage]`  | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'`   | Vị trí của vùng thông tin bổ trợ (Tổng trang & Nhảy trang).     |
| `[numberPageDisplay]`                | `number`                                 | `5`          | Số lượng các nút trang (con số) hiển thị trên thanh điều hướng. |
| `[perPage]`                          | `number`                                 | **Bắt buộc** | Số lượng phần tử hiển thị trên mỗi trang.                       |
| `[showInputGotoPage]`                | `boolean`                                | `false`      | Hiển thị ô nhập để nhảy nhanh đến trang bất kỳ.                 |
| `[showTotalPage]`                    | `boolean`                                | `false`      | Hiển thị thông báo tổng số trang.                               |
| `[totalItems]`                       | `number`                                 | **Bắt buộc** | Tổng số lượng phần tử cần phân trang.                           |

#### Models (Two-way bindings)

| Property          | Type     | Description                               |
| ----------------- | -------- | ----------------------------------------- |
| `[(currentPage)]` | `number` | Trang hiện tại đang được chọn (bắt buộc). |

#### Outputs

| Property          | Type     | Description                                       |
| ----------------- | -------- | ------------------------------------------------- |
| `(outPageSelect)` | `number` | Phát ra số trang mới khi người dùng chuyển trang. |

## Hidden Logic

### 1. Debounced Navigation

Khi người dùng nhập số trang vào ô "Go to page", component sẽ chờ **1500ms** (debounce) trước khi thực hiện chuyển trang để tránh spam request. Tuy nhiên, nếu nhấn **Enter**, trang sẽ được chuyển ngay lập tức.

### 2. Boundary Protection

Nếu `currentPage` được cung cấp lớn hơn tổng số trang thực tế (`totalPage`), component sẽ tự động điều chỉnh `currentPage` về giá trị `totalPage` để đảm bảo tính hợp lệ của dữ liệu.

### 3. Dynamic Page Window

Danh sách các nút số trang hiển thị được tính toán linh hoạt bao quanh `currentPage` dựa trên `numberPageDisplay`, giúp tối ưu không gian hiển thị khi có hàng trăm trang.

## Công nghệ

| Technology      | Version | Purpose           |
| --------------- | ------- | ----------------- |
| Angular         | 18+     | Framework         |
| Angular Signals | -       | State management  |
| RxJS            | 7.x     | Debounce handling |
| OnPush          | -       | Performance       |

## Demo

```bash
npx nx serve core-ui
```

Truy cập: `http://localhost:4200/pagination`