npm package: @libs-ui/components-tags
Description: > Library Angular Component quản lý và hiển thị danh sách các thẻ (Tags/Labels) với hỗ trợ tìm kiếm, lựa chọn từ danh sách, và tùy chỉnh giao diện mạnh mẽ.
Latest version: 0.2.356-23

# @libs-ui/components-tags

> Library Angular Component quản lý và hiển thị danh sách các thẻ (Tags/Labels) với hỗ trợ tìm kiếm, lựa chọn từ danh sách, và tùy chỉnh giao diện mạnh mẽ.

## Giới thiệu

`LibsUiComponentsTagsComponent` là một component linh hoạt cho phép người dùng chọn một hoặc nhiều mục từ một danh sách hoặc nhập trực tiếp. Nó hỗ trợ hiển thị avatar, các trạng thái validation, tìm kiếm online/offline, và tích hợp sâu với `libs_ui-components-list` và `libs_ui-components-popover`.

### Tính năng

- ✅ **Multiple Selection**: Chọn nhiều mục cùng lúc.
- ✅ **Single Selection**: Chế độ chọn một mục duy nhất (UI giống dropdown).
- ✅ **Search Online/Offline**: Tìm kiếm linh hoạt từ local data hoặc qua API.
- ✅ **Avatar Support**: Tự động hiển thị avatar hoặc text avatar cho mỗi tag.
- ✅ **Enter to Add**: Cho phép tạo mới tag bằng cách nhấn Enter.
- ✅ **Validation**: Hỗ trợ required, max items, và pattern validation.
- ✅ **Custom Styling**: Tùy chỉnh màu sắc, border cho từng tag qua config.
- ✅ **OnPush Change Detection**: Tối ưu hiệu năng.

## Khi nào sử dụng

- Trong các form cần chọn nhiều nhãn (labels), người nhận (recipients), hoặc phân loại (categories).
- Khi cần một bộ chọn (selector) có khả năng tìm kiếm mạnh mẽ và hiển thị thông tin phong phú (ảnh, tên).
- Thay thế cho các input text thuần túy khi dữ liệu có cấu trúc.

## Cài đặt

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

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

## Import

```typescript
import { LibsUiComponentsTagsComponent } from '@libs-ui/components-tags';

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

## Ví dụ

### Basic Usage

```html
<libs_ui-components-tags
  [listConfig]="listConfig"
  [(keysSelected)]="selectedKeys"
  placeholder="Chọn nhãn..." />
```

```typescript
// Trong component class
readonly listConfig: IListConfigItem = {
  // Config cho LibsUiComponentsListComponent
  httpRequest: {
    url: '/api/tags',
    method: 'GET'
  }
};
readonly selectedKeys = signal<string[]>([]);
```

## API

### libs_ui-components-tags

#### Inputs

| Property                       | Type                    | Default                 | Description                                                 |
| ------------------------------ | ----------------------- | ----------------------- | ----------------------------------------------------------- |
| `[config]`                     | `ITagsConfig`           | `undefined`             | Cấu hình chuyên sâu cho giao diện và logic của tags.        |
| `[listConfig]`                 | `IListConfigItem`       | `undefined`             | Cấu hình cho danh sách gợi ý (Popover list).                |
| `[placeholder]`                | `string`                | `'i18n_import_content'` | Nội dung placeholder khi chưa có tag nào hoặc đang focus.   |
| `[singleSelected]`             | `boolean`               | `false`                 | Nếu `true`, chỉ cho phép chọn duy nhất một mục.             |
| `[maxItemInput]`               | `number`                | `undefined`             | Giới hạn số lượng tag tối đa có thể chọn.                   |
| `[defaultKeysSelected]`        | `Array<any>`            | `undefined`             | Danh sách các keys mặc định được chọn ban đầu.              |
| `[httpRequestDetailItemByIds]` | `IHttpRequestConfig`    | `undefined`             | API dùng để lấy thông tin chi tiết các items dựa trên keys. |
| `[disable]`                    | `boolean`               | `false`                 | Vô hiệu hóa component.                                      |
| `[readonly]`                   | `boolean`               | `false`                 | Chế độ chỉ đọc, không thể xóa hoặc thêm tag.                |
| `[zIndex]`                     | `number`                | `1000`                  | z-index cho popover list.                                   |
| `[fieldLabel]`                 | `string`                | `'label'`               | Tên trường hiển thị label cho tag.                          |
| `[defaultItemsSelected]`       | `Array<any>`            | `[]`                    | Danh sách các item object được chọn ban đầu.                |
| `[isSearchOnline]`             | `boolean`               | `false`                 | Tìm kiếm online (qua API) hay offline (local).              |
| `[maxItemInput]`               | `number`                | `undefined`             | Giới hạn số lượng tag tối đa có thể chọn.                   |
| `[validMaxItemSelected]`       | `IValidMaxItemSelected` | `undefined`             | Cấu hình validation cho số lượng item tối đa.               |
| `[validPattern]`               | `IValidPattern[]`       | `undefined`             | Cấu hình validation theo pattern (regex).                   |
| `[fieldGetImage]`              | `string`                | `undefined`             | Tên trường lấy URL ảnh avatar.                              |
| `[imageSize]`                  | `number`                | `16`                    | Kích thước avatar (16, 24, 32, ...).                        |
| `[keysDisableItem]`            | `Array<any>`            | `[]`                    | Danh sách keys bị vô hiệu hóa (không thể xóa).              |
| `[validRequired]`              | `IMessageTranslate`     | `undefined`             | Message lỗi khi không có tag nào được chọn.                 |
| `[showListBellow]`             | `boolean`               | `false`                 | Luôn hiển thị danh sách gợi ý bên dưới.                     |
| `[enterAutoAddTagToList]`      | `boolean`               | `false`                 | Tự động thêm tag mới vào danh sách khi nhấn Enter.          |

#### Outputs

| Property                        | Type                        | Description                                                |
| ------------------------------- | --------------------------- | ---------------------------------------------------------- |
| `(outSelectMultiItem)`          | `Array<any>`                | Emit danh sách các đối tượng (items) đã được chọn.         |
| `(outFunctionsControl)`         | `ITagsFunctionControlEvent` | Cung cấp các methods để điều khiển component từ bên ngoài. |
| `(outValidEvent)`               | `boolean`                   | Emit trạng thái validation (true nếu hợp lệ).              |
| `(outClickButtonOther)`         | `IButton`                   | Emit khi click vào nút khác trên danh sách.                |
| `(outShowListEvent)`            | `boolean`                   | Emit khi ẩn/hiện danh sách gợi ý.                          |
| `(outLoadingGetDetailSelected)` | `boolean`                   | Emit trạng thái loading khi lấy chi tiết item qua API.     |

## Types & Interfaces

```typescript
export interface ITagsConfig {
  getValue?: (item: unknown) => string; // Hàm custom lấy label
  getStyles?: (item: unknown) => any; // Hàm custom style cho tag
  getDisableItem?: (item: unknown) => boolean; // Disable click xóa cho tag cụ thể
  ignoreInput?: boolean; // Ẩn input nhập text
  uiLikeDropdown?: boolean; // Giao diện giống dropdown classic
  directionList?: TYPE_POPOVER_DIRECTION; // Hướng hiển thị danh sách
  // ... (see source for all options)
}

export interface ITagsFunctionControlEvent {
  checkIsValid: () => Promise<boolean>;
  clearItemSelected: (ignoreValid?: boolean) => Promise<void>;
  focusInput: () => Promise<void>;
  refreshListData: () => Promise<void>;
  resetToDefaultDataSelected: (item?: Array<unknown>) => Promise<void>;
  // ... (see source for all methods)
}
```

## Demo

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

Truy cập: `http://localhost:4500/tags`

## Unit Tests

```bash
npx nx test components-tags
```

## License

MIT