@libs-ui/components-pagination 0.2.355-9 → 0.2.356-1

package/README.md

@@ -1,3 +1,130 @@
-# pagination
+# @libs-ui/components-pagination
 
-This library was generated with [Nx](https://nx.dev).
+> 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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libs-ui/components-pagination",
-  "version": "0.2.355-9",
+  "version": "0.2.356-1",
   "peerDependencies": {
     "@angular/common": ">=18.0.0",
     "@angular/core": ">=18.0.0"