npm package: @libs-ui/components-checkbox-group
Description: > Component quản lý nhóm các checkbox với tính năng validation và cấu hình layout linh hoạt cho Angular.
Latest version: 0.2.356-23

# @libs-ui/components-checkbox-group

> Component quản lý nhóm các checkbox với tính năng validation và cấu hình layout linh hoạt cho Angular.

## Giới thiệu

`LibsUiComponentsCheckboxGroupComponent` là một standalone component cho phép hiển thị và quản lý một tập hợp các checkbox. Nó kế thừa đầy đủ sức mạnh của `CheckboxSingleComponent` cho mỗi item trong nhóm và bổ sung các tính năng quản lý tập trung:

- ✅ Quản lý trạng thái chọn hàng loạt thông qua `model`.
- ✅ Hỗ trợ validation bắt buộc chọn (Required selection).
- ✅ Cấu hình giao diện hàng ngang hoặc hàng dọc.
- ✅ Tích hợp nhanh với danh sách keys để set trạng thái chọn/vô hiệu hóa.
- ✅ Hỗ trợ nội dung bổ sung (subText/subTemplate) cho mỗi item.

## Cài đặt

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

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

## Sử dụng

### Import Component

```typescript
import { Component, signal } from '@angular/core';
import { LibsUiComponentsCheckboxGroupComponent, ICheckboxGroupItem } from '@libs-ui/components-checkbox-group';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [LibsUiComponentsCheckboxGroupComponent],
  template: `
    <libs_ui-components-checkbox-group
      [(groups)]="options"
      [labelConfig]="{ label: 'Chọn sở thích' }"></libs_ui-components-checkbox-group>
  `,
})
export class ExampleComponent {
  options = signal<ICheckboxGroupItem[]>([{ item: { key: 'music', label: 'Âm nhạc' } }, { item: { key: 'sport', label: 'Thể thao' } }, { item: { key: 'reading', label: 'Đọc sách' } }]);
}
```

## API Reference

### Inputs

| Tên                            | Kiểu                          | Mặc định      | Mô tả                                                          |
| ------------------------------ | ----------------------------- | ------------- | -------------------------------------------------------------- |
| `classGroupWhenModeHorizontal` | `string`                      | `'flex'`      | Class CSS cho wrapper khi ở chế độ chiều ngang.                |
| `classInclude`                 | `string`                      | `undefined`   | Class CSS bổ sung cho container chính.                         |
| `classItemWhenModeHorizontal`  | `string`                      | `'mr-[24px]'` | Class CSS cho mỗi item khi ở chế độ chiều ngang.               |
| `classLabelInclude`            | `string`                      | `undefined`   | Class CSS cho nhãn tổng quát của nhóm.                         |
| `clickExactly`                 | `boolean`                     | `true`        | Nếu `true`, chỉ click vào checkbox/label mới đổi trạng thái.   |
| `disable`                      | `boolean`                     | `false`       | Vô hiệu hóa tương tác cho toàn bộ nhóm.                        |
| `fieldKey`                     | `string`                      | `'key'`       | Tên thuộc tính dùng làm khóa định danh cho item dữ liệu.       |
| `groups`                       | `model<ICheckboxGroupItem[]>` | _required_    | Danh sách các item trong nhóm (hỗ trợ two-way binding).        |
| `horizontal`                   | `boolean`                     | `false`       | Nếu `true`, hiển thị các item theo hàng ngang.                 |
| `keysChecked`                  | `string[]`                    | `undefined`   | Danh sách keys của các item cần được chọn sẵn.                 |
| `keysDisable`                  | `string[]`                    | `undefined`   | Danh sách keys của các item cần được vô hiệu hóa.              |
| `labelConfig`                  | `ILabel`                      | `undefined`   | Cấu hình cho component Label hiển thị trên cùng của nhóm.      |
| `modeBorder`                   | `boolean`                     | `false`       | Hiển thị viền bao quanh component.                             |
| `showValidateBottom`           | `boolean`                     | `false`       | Hiển thị thông báo lỗi validation ở dưới cùng.                 |
| `validRequired`                | `ICheckboxGroupValidRequired` | `undefined`   | Cấu hình validation bắt buộc người dùng chọn ít nhất một item. |

### Outputs

| Tên                   | Kiểu                                 | Mô tả                                                                        |
| --------------------- | ------------------------------------ | ---------------------------------------------------------------------------- |
| `outChange`           | `ICheckboxEvent`                     | Phát ra khi bất kỳ checkbox nào trong nhóm thay đổi trạng thái.              |
| `outFunctionsControl` | `ICheckboxGroupFunctionControlEvent` | Cung cấp các hàm điều khiển (API) như `checkIsValid`, `reset`, `resetError`. |

## Interfaces & Types

### ICheckboxGroupItem

```typescript
interface ICheckboxGroupItem {
  item: ICheckboxItem; // Cấu hình checkbox (xem CheckboxSingle)
  subText?: string; // Văn bản bổ sung
  subTemplate?: TemplateRef; // Template tùy chỉnh bổ sung
  disableByKeys?: boolean; // Trạng thái disable tự động theo keysDisable
}
```

### ICheckboxGroupFunctionControlEvent

```typescript
interface ICheckboxGroupFunctionControlEvent {
  checkIsValid: () => Promise<boolean>; // Kiểm tra tính hợp lệ (validation)
  resetError: () => Promise<void>; // Xóa hiển thị lỗi
  reset: () => Promise<void>; // Reset toàn bộ về trạng thái chưa chọn
}
```

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

- **Angular 18+** - Standalone Components
- **Angular Signals & Model** - Modern reactive state management
- **NG-Zorro Style Integration**

## 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-group/checkbox-group.component.ts`

### Tính năng Demo

- 🎮 **Basic Group**: Sử dụng cơ bản với danh sách dọc.
- ↔️ **Horizontal Layout**: Hiển thị items theo hàng ngang.
- ⚠️ **Validation**: Demo tính năng bắt buộc chọn với thông báo lỗi.
- 🛠️ **External Control**: Điều khiển nhóm checkbox bằng API (Reset, Validate).

## License

MIT