npm package: @libs-ui/components-checkbox-single
Description: > Component checkbox đơn lẻ với nhiều tùy chọn hiển thị và tích hợp nâng cao cho Angular.
Latest version: 0.2.356-23

# @libs-ui/components-checkbox-single

> Component checkbox đơn lẻ với nhiều tùy chọn hiển thị và tích hợp nâng cao cho Angular.

## Giới thiệu

`LibsUiComponentsCheckboxSingleComponent` là một standalone Angular component cung cấp giải pháp checkbox linh hoạt, không chỉ đơn thuần là một ô chọn mà còn tích hợp nhiều yếu tố UI phổ biến như:

- ✅ Hiển thị nhãn (label) với định dạng linh hoạt
- ✅ Tích hợp Popover (tooltip) khi di chuột vào nhãn
- ✅ Hiển thị hình ảnh hoặc Avatar cạnh checkbox
- ✅ Hỗ trợ Bullet (chấm tròn màu) để phân loại
- ✅ Hiển thị Description (mô tả chi tiết dưới nhãn)
- ✅ Hỗ trợ Component Outlet để render nội dung tùy chỉnh
- ✅ Trạng thái Error và Disable toàn diện
- ✅ Sử dụng Angular Signals & Model cho reactivity tối ưu

## Cài đặt

```bash
# npm
npm install @libs-ui/components-checkbox-single

# yarn
yarn add @libs-ui/components-checkbox-single
```

## Sử dụng

### Import Component

```typescript
import { Component, signal } from '@angular/core';
import { LibsUiComponentsCheckboxSingleComponent, ICheckboxEvent } from '@libs-ui/components-checkbox-single';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [LibsUiComponentsCheckboxSingleComponent],
  template: `
    <libs_ui-components-checkbox-single
      [(checked)]="isSelected"
      label="Chấp nhận điều khoản"
      (outChange)="onStatusChange($event)"></libs_ui-components-checkbox-single>
  `,
})
export class ExampleComponent {
  isSelected = signal(false);

  onStatusChange(event: ICheckboxEvent) {
    console.log('Trạng thái checkbox:', event.checked);
  }
}
```

## API Reference

### Inputs

| Tên                      | Kiểu                         | Mặc định             | Mô tả                                                                                                        |
| ------------------------ | ---------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------ |
| `avatarConfig`           | `IAvatarConfig`              | `undefined`          | Cấu hình cho component Avatar hiển thị cạnh checkbox.                                                        |
| `bullet`                 | `ICheckboxBullet`            | `undefined`          | Cấu hình cho dấu chấm tròn màu (bullet) hiển thị cạnh checkbox.                                              |
| `checked`                | `model<boolean>`             | `false`              | Trạng thái chọn của checkbox (hỗ trợ two-way binding).                                                       |
| `classIconInclude`       | `string`                     | `undefined`          | Class CSS bổ sung cho thẻ chứa icon.                                                                         |
| `classImageInclude`      | `string`                     | `undefined`          | Class CSS bổ sung cho phần hình ảnh.                                                                         |
| `classInclude`           | `string`                     | `''`                 | Class CSS bổ sung cho container chính của component.                                                         |
| `classLabelInclude`      | `string`                     | `'libs-ui-font-h5r'` | Class CSS cho phần nhãn văn bản.                                                                             |
| `clickExactly`           | `boolean`                    | `true`               | Nếu `true`, chỉ click vào checkbox/label mới đổi trạng thái. Nếu `false`, click vào toàn bộ area sẽ trigger. |
| `componentOutlet`        | `any`                        | `undefined`          | Component tùy chỉnh để render thông qua `ngComponentOutlet`.                                                 |
| `dataComponentOutlet`    | `TYPE_COMPONENT_OUTLET_DATA` | `undefined`          | Dữ liệu truyền vào cho `componentOutlet`.                                                                    |
| `description`            | `ICheckboxItemDescription`   | `undefined`          | Nội dung mô tả chi tiết hiển thị bên dưới nhãn.                                                              |
| `disable`                | `boolean`                    | `false`              | Vô hiệu hóa toàn bộ tương tác với checkbox.                                                                  |
| `disableLabel`           | `boolean`                    | `false`              | Vô hiệu hóa tương tác click trên nhãn văn bản.                                                               |
| `error`                  | `boolean`                    | `false`              | Đánh dấu checkbox đang ở trạng thái lỗi.                                                                     |
| `iconImageClass`         | `string`                     | `undefined`          | Class icon (ví dụ: `fa fa-user`) hiển thị cạnh checkbox.                                                     |
| `ignoreCheckbox`         | `boolean`                    | `false`              | Ẩn ô chọn checkbox, chỉ hiển thị nhãn và các thành phần khác.                                                |
| `ignoreShowPopoverLabel` | `boolean`                    | `false`              | Nếu `true`, sẽ không hiển thị popover khi di chuột vào nhãn.                                                 |
| `imgTypeIcon`            | `boolean`                    | `false`              | Xác định hình ảnh truyền vào là dạng icon.                                                                   |
| `key`                    | `string`                     | `undefined`          | Khóa định danh duy nhất cho checkbox.                                                                        |
| `label`                  | `string`                     | `undefined`          | Văn bản hiển thị cho nhãn checkbox.                                                                          |
| `linkImage`              | `model<string>`              | `undefined`          | URL hình ảnh hiển thị cạnh checkbox.                                                                         |
| `linkImageError`         | `string`                     | `undefined`          | URL hình ảnh hiển thị khi `linkImage` bị lỗi load.                                                           |
| `modeBorder`             | `boolean`                    | `false`              | Hiển thị viền bao quanh toàn bộ component.                                                                   |
| `popover`                | `IPopover`                   | `undefined`          | Cấu hình Popover hiển thị khi di chuột vào nhãn.                                                             |
| `showBorderError`        | `boolean`                    | `false`              | Hiển thị viền đỏ bao quanh khi `error` là `true`.                                                            |
| `stillOtherOptions`      | `boolean`                    | `false`              | Hiển thị trạng thái "còn các lựa chọn khác" (dạng mờ/indicator).                                             |
| `typeLabelPopover`       | `'text' \| 'component'`      | `'text'`             | Loại nội dung của popover trên nhãn.                                                                         |
| `zIndexLabel`            | `number`                     | `1200`               | Giá trị z-index cho phần nhãn và popover.                                                                    |

### Outputs

| Tên                             | Kiểu                 | Mô tả                                                                                 |
| ------------------------------- | -------------------- | ------------------------------------------------------------------------------------- |
| `outChange`                     | `ICheckboxEvent`     | Phát ra khi trạng thái `checked` thay đổi. Gửi kèm key, trạng thái mới và hàm revert. |
| `outChangStageFlagMousePopover` | `IFlagMouse`         | Phát ra khi trạng thái chuột thay đổi trên vùng nhãn (để điều khiển popover).         |
| `outClickLabel`                 | `void`               | Phát ra khi người dùng click trực tiếp vào nhãn văn bản.                              |
| `outEventPopover`               | `TYPE_POPOVER_EVENT` | Phát ra các sự kiện tương tác từ Popover.                                             |

## Interfaces & Types

### ICheckboxEvent

```typescript
interface ICheckboxEvent {
  key: any;
  checked: boolean;
  allCheckboxChecked?: Array<ICheckboxChecked>;
  revert: () => void;
}
```

### ICheckboxItemDescription

```typescript
interface ICheckboxItemDescription {
  content: string; // Nội dung mô tả (Hỗ trợ HTML)
  classInclude: string; // Class CSS bổ sung
}
```

### ICheckboxBullet

```typescript
interface ICheckboxBullet {
  classInclude?: string;
  backgroundColor: string;
  width: number;
  height: number;
}
```

## Công nghệ sử dụng

- **Angular 18+** - Standalone Components
- **Angular Signals & Model** - Modern reactive state management
- **NG-Zorro Style Integration** - Tuân thủ phong cách thiết kế chuyên nghiệp

## Demo

Demo có sẵn trong ứng dụng `core-ui`:

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

**File demo:** `apps/core-ui/src/app/components/checkbox-single/checkbox-single.component.ts`

### Tính năng Demo

- 🎮 **Basic Usage**: Sử dụng cơ bản với nhãn và trạng thái.
- 🖼️ **Image & Avatar**: Kết hợp checkbox với hình ảnh minh họa.
- 💡 **Popover & Description**: Hiển thị thông tin chi tiết khi tương tác.
- 🛠️ **Interactive Demo**: Thử nghiệm các flag `disable`, `error`, `ignoreCheckbox`.

## Unit Tests

```bash
# Chạy tests
npx nx test components-checkbox-single
```

## License

MIT