@libs-ui/components-buttons-sort 0.2.355-9 → 0.2.356-0

package/README.md

@@ -1,17 +1,27 @@
-# Sort
+# Buttons Sort Component
+
+> Version: `0.2.355-14`
+>
+> Component nút sort (asc/desc) gọn nhẹ, hỗ trợ disable theo chiều và emit payload `ISort` kèm hàm `reset()`.
 
 ## Giới thiệu
 
-`@libs-ui/components-buttons-sort` là một component Sort Button cho Angular, hiển thị hai biểu tượng sắp xếp tăng dần và giảm dần, hỗ trợ binding trạng thái và emit event khi thay đổi.
+Package `@libs-ui/components-buttons-sort` cung cấp 2 component:
+
+- `LibsUiComponentsButtonsSortComponent`: 2 nút riêng cho `asc` và `desc`
+- `LibsUiComponentsButtonsSortArrowComponent`: 1 nút toggle `asc` ↔ `desc`, có thể bật popover mô tả
 
 ## Tính năng
 
-- Hiển thị icon `asc` và `desc` với kích thước tuỳ chỉnh
-- Two-way binding cho chế độ sort (`mode`)
-- Tuỳ chọn fieldSort để gắn tên trường sắp xếp
-- Hỗ trợ disable toàn bộ sort hoặc riêng `asc` / `desc`
-- `onlyEmit` để chỉ emit sự kiện mà không tự thay đổi chế độ
-- Emit `ISort` bao gồm `mode`, `modeNumber`, `fieldSort` và hàm `reset()`
+- ✅ Có 2 kiểu UI: **2 nút (Sort)** và **1 nút toggle (Arrow)**
+- ✅ Sort 2 chiều: `asc` / `desc`
+- ✅ Two-way binding qua `[(mode)]`
+- ✅ Emit payload `(outChange)` kiểu `ISort`
+- ✅ Hỗ trợ disable toàn bộ hoặc disable từng chiều (`disableAsc`, `disableDesc`)
+- ✅ Hỗ trợ `onlyEmit` để luôn emit event theo click
+- ✅ Arrow hỗ trợ `defaultMode` và popover content (asc/desc)
+- ✅ OnPush Change Detection
+- ✅ Angular Signals
 
 ## Cài đặt
 
@@ -19,121 +29,164 @@
 npm install @libs-ui/components-buttons-sort
 ```
 
-hoặc
+## Import
 
-```bash
-yarn add @libs-ui/components-buttons-sort
+```typescript
+import { Component } from '@angular/core';
+import { LibsUiComponentsButtonsSortArrowComponent, LibsUiComponentsButtonsSortComponent, ISort, TYPE_SORT_TYPE } from '@libs-ui/components-buttons-sort';
+
+@Component({
+  standalone: true,
+  imports: [LibsUiComponentsButtonsSortArrowComponent, LibsUiComponentsButtonsSortComponent],
+  template: '',
+})
+export class ExampleComponent {}
 ```
 
-## Sử dụng
+## Cách sử dụng
+
+### 1. Ví dụ inline template
 
-### Inline Template
+```html
+<libs_ui-components-buttons-sort
+  [fieldSort]="'name'"
+  [(mode)]="mode"
+  (outChange)="onChange($event)"
+/>
+```
 
 ```typescript
-import { Component } from '@angular/core';
-import { LibsUiComponentsButtonsSortComponent } from '@libs-ui/components-buttons-sort';
-import { TYPE_SORT_TYPE } from '@libs-ui/components-buttons-sort';
+import { Component, signal } from '@angular/core';
+import { LibsUiComponentsButtonsSortComponent, ISort, TYPE_SORT_TYPE } from '@libs-ui/components-buttons-sort';
 
 @Component({
-  selector: 'app-example',
   standalone: true,
   imports: [LibsUiComponentsButtonsSortComponent],
   template: `
     <libs_ui-components-buttons-sort
-      [size]="20"
-      [(mode)]="demoMode"
       [fieldSort]="'name'"
-      (outChange)="onSort($event)"></libs_ui-components-buttons-sort>
+      [(mode)]="mode()"
+      (outChange)="onChange($event)"
+    />
   `,
 })
-export class ExampleComponent {
-  demoMode: TYPE_SORT_TYPE = '';
-  onSort(event: any) {
-    console.log('Sorted:', event);
+export class InlineExampleComponent {
+  readonly mode = signal<TYPE_SORT_TYPE>('');
+
+  onChange(sort: ISort): void {
+    console.log(sort.mode, sort.fieldSort);
   }
 }
 ```
 
-### File HTML riêng
+### 2. Arrow - 1 nút toggle (có thể bật popover)
+
+```html
+<libs_ui-components-buttons-sort-arrow
+  [fieldSort]="'name'"
+  [ignorePopoverContent]="false"
+  [popoverContentAsc]="'Sắp xếp tăng dần (A → Z)'"
+  [popoverContentDesc]="'Sắp xếp giảm dần (Z → A)'"
+  [defaultMode]="'asc'"
+  [(mode)]="mode"
+  (outChange)="onChange($event)"
+/>
+```
+
+### 2. Ví dụ với file HTML riêng
+
+`example.component.html`
+
+```html
+<libs_ui-components-buttons-sort
+  [size]="14"
+  [disableAsc]="true"
+  [fieldSort]="'createdAt'"
+  [(mode)]="mode"
+  (outChange)="onChange($event)"
+/>
+```
+
+`example.component.ts`
 
 ```typescript
-import { Component } from '@angular/core';
-import { LibsUiComponentsButtonsSortComponent } from '@libs-ui/components-buttons-sort';
-import { TYPE_SORT_TYPE } from '@libs-ui/components-buttons-sort';
+import { Component, signal } from '@angular/core';
+import { LibsUiComponentsButtonsSortComponent, ISort, TYPE_SORT_TYPE } from '@libs-ui/components-buttons-sort';
 
 @Component({
-  selector: 'app-example',
   standalone: true,
   imports: [LibsUiComponentsButtonsSortComponent],
   templateUrl: './example.component.html',
 })
-export class ExampleComponent {
-  demoMode: TYPE_SORT_TYPE = '';
-  onSort(event: any) {}
-}
-```
+export class HtmlFileExampleComponent {
+  readonly mode = signal<TYPE_SORT_TYPE>('');
 
-```html
-<libs_ui-components-buttons-sort
-  [size]="20"
-  [(mode)]="demoMode"
-  [fieldSort]="'name'"
-  (outChange)="onSort($event)"></libs_ui-components-buttons-sort>
+  onChange(sort: ISort): void {
+    // sort.reset() có thể dùng để reset mode về ''
+    console.log(sort);
+  }
+}
 ```
 
-## Công nghệ sử dụng
+## Công nghệ
 
-- **Angular 18** với standalone components và Signals
-- **Tailwind CSS** 3.x (phong cách demo)
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| Angular | 18+ | Framework |
+| Angular Signals | - | State management |
+| TailwindCSS | 3.x | Styling (demo) |
+| OnPush | - | Change Detection |
 
-## API Reference
+## API
 
-### Inputs
+### libs_ui-components-buttons-sort
 
-| Tên         | Kiểu             | Mặc định | Mô tả                                                 |
-| ----------- | ---------------- | -------- | ----------------------------------------------------- |
-| size        | `number`         | `10`     | Độ lớn của icon sắp xếp (px).                         |
-| mode        | `TYPE_SORT_TYPE` | `''`     | Thứ tự hiện tại ('asc', 'desc' hoặc không sắp xếp).   |
-| fieldSort   | `string`         | `''`     | Trường dữ liệu dùng để sắp xếp.                       |
-| disable     | `boolean`        | `false`  | Nếu true: tắt chức năng sắp xếp.                      |
-| disableAsc  | `boolean`        | `false`  | Nếu true: vô hiệu hóa chế độ sắp xếp tăng dần.        |
-| disableDesc | `boolean`        | `false`  | Nếu true: vô hiệu hóa chế độ sắp xếp giảm dần.        |
-| onlyEmit    | `boolean`        | `false`  | Nếu true: chỉ phát sự kiện, không tự thay đổi chế độ. |
+#### Inputs
 
-### Outputs
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `[disable]` | `boolean` | `false` | Disable toàn bộ sort |
+| `[disableAsc]` | `boolean` | `false` | Disable chiều asc |
+| `[disableDesc]` | `boolean` | `false` | Disable chiều desc |
+| `[defaultMode]` | `TYPE_SORT_TYPE` | `''` | Chỉ áp dụng cho Arrow: mode mặc định khi click lần đầu |
+| `[fieldSort]` | `string` | `''` | Field đang sort (được trả về trong `ISort`) |
+| `[ignorePopoverContent]` | `boolean` | `true` | Chỉ áp dụng cho Arrow: bỏ qua hiển thị popover content |
+| `[onlyEmit]` | `boolean` | `false` | Chỉ emit event, không chặn khi mode đang trùng |
+| `[popoverContentAsc]` | `string \| undefined` | `undefined` | Chỉ áp dụng cho Arrow: nội dung popover khi asc |
+| `[popoverContentDesc]` | `string \| undefined` | `undefined` | Chỉ áp dụng cho Arrow: nội dung popover khi desc |
+| `[size]` | `number` | `10` | Kích thước icon sort (px) |
+| `[zIndex]` | `number` | `10` | Chỉ áp dụng cho Arrow: zIndex của popover |
+| `[(mode)]` | `TYPE_SORT_TYPE` | `''` | Mode sort hiện tại: `asc` / `desc` / `''` |
 
-| Tên       | Kiểu                     | Mô tả                                                   |
-| --------- | ------------------------ | ------------------------------------------------------- |
-| outChange | `(event: ISort) => void` | Trả về đối tượng ISort khi trạng thái sắp xếp thay đổi. |
+#### Outputs
 
-### Interfaces
+| Property | Type | Description |
+|----------|------|-------------|
+| `(outChange)` | `EventEmitter<ISort>` | Emit khi người dùng click sort, trả về payload `ISort` |
 
-#### `ISort`
+## Types & Interfaces
 
 ```typescript
+export type TYPE_SORT_TYPE = 'asc' | 'desc' | '';
+
 export interface ISort {
   mode: TYPE_SORT_TYPE;
-  modeNumber: 1 | 2;
+  modeNumber: 1 | 2; // 1: asc; 2:desc
   fieldSort: string;
   reset: () => void;
 }
 ```
 
-Mô tả:
+### Mô tả Types
 
-- `mode`: `'asc'`, `'desc'` hoặc `''` (không sắp xếp).
-- `modeNumber`: số tương ứng (1 = `'asc'`, 2 = `'desc'`).
-- `fieldSort`: tên trường dữ liệu dùng để sắp xếp.
-- `reset()`: hàm đặt lại về trạng thái không sắp xếp.
+- **TYPE_SORT_TYPE**: Kiểu mode sort: `asc`, `desc`, hoặc rỗng (không sort).
+- **ISort**: Payload emit ra khi sort thay đổi, có `reset()` để reset mode.
 
-#### `TYPE_SORT_TYPE`
+## Demo
 
-```typescript
-export type TYPE_SORT_TYPE = 'asc' | 'desc' | '';
+```bash
+npx nx serve core-ui
 ```
 
-Mô tả:
+Truy cập: `http://localhost:4500/buttons/sort`
 
-- `'asc'`: sắp xếp tăng dần.
-- `'desc'`: sắp xếp giảm dần.
-- `''`: không sắp xếp.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@libs-ui/components-buttons-sort",
-  "version": "0.2.355-9",
+  "version": "0.2.356-0",
   "peerDependencies": {
     "@angular/core": ">=18.0.0",
-    "@libs-ui/components-popover": "0.2.355-9"
+    "@libs-ui/components-popover": "0.2.356-0"
   },
   "sideEffects": false,
   "module": "fesm2022/libs-ui-components-buttons-sort.mjs",