@libs-ui/components-dropdown 0.2.356-9 → 0.2.357-1

package/README.md

@@ -1,52 +1,39 @@
 # @libs-ui/components-dropdown
 
-> Component dropdown đa năng hỗ trợ nhiều chế độ hiển thị: text, radio, checkbox, group. Tích hợp sẵn tìm kiếm, validation, popover, tabs và điều khiển từ bên ngoài.
-
-**Version:** `0.2.355-14`
+> Component dropdown đa năng hỗ trợ nhiều chế độ hiển thị: text, radio, checkbox, group, tree, JSON tree. Tích hợp sẵn tìm kiếm, validation, popover overlay, tabs phân loại và điều khiển từ bên ngoài qua FunctionControl.
 
 ## Giới thiệu
 
-`LibsUiComponentsDropdownComponent` là một standalone Angular component cung cấp dropdown selection với nhiều chế độ hiển thị và tính năng nâng cao.
+`LibsUiComponentsDropdownComponent` là một standalone Angular component cung cấp dropdown selection với nhiều chế độ hiển thị và tính năng nâng cao. Component tự động load dữ liệu từ API thông qua `IHttpRequestConfig`, hỗ trợ cả chọn đơn và chọn nhiều, đồng thời cung cấp `FunctionControl` để component cha có thể điều khiển (reset, refresh, validate) từ bên ngoài.
 
-### Tính năng
+## Tính năng
 
-- ✅ Nhiều chế độ hiển thị: text, radio, checkbox, group
-- ✅ Tìm kiếm online/offline tích hợp sẵn
-- ✅ Validation (required, max items selected)
-- ✅ Điều khiển từ bên ngoài qua `IDropdownFunctionControlEvent`
-- ✅ Hỗ trợ tabs để phân loại dữ liệu
-- ✅ Tự động load dữ liệu từ API (httpRequestData)
-- ✅ Auto-select first item / all items
-- ✅ Hiển thị avatar, icon, image cho item
-- ✅ Custom content qua ng-content
-- ✅ OnPush Change Detection
-- ✅ Angular Signals
+- ✅ Nhiều chế độ hiển thị: `text`, `radio`, `checkbox`, `group` (tree, JSON tree, personalize)
+- ✅ Tìm kiếm online (gọi API) và offline (client-side) tích hợp sẵn
+- ✅ Validation: required, giới hạn số lượng item được chọn tối đa
+- ✅ Điều khiển từ bên ngoài qua `IDropdownFunctionControlEvent` (reset, refresh, setError, setItemSelectedByKey...)
+- ✅ Hỗ trợ tabs để phân loại dữ liệu theo nhóm
+- ✅ Tự động load và auto-select item đầu tiên hoặc toàn bộ (autoSelectFirstItem / autoSelectAllItem)
+- ✅ Hiển thị avatar, icon, image cho từng item trong danh sách
+- ✅ Custom content qua `ng-content` (`[isNgContent]="true"`)
+- ✅ Tùy chỉnh popover overlay (hướng, width, z-index, animation...)
+- ✅ Lazy-load chi tiết item theo key (`httpRequestDetailItemById`)
+- ✅ OnPush Change Detection + Angular Signals
 
 ## Khi nào sử dụng
 
-- Chọn một hoặc nhiều giá trị từ danh sách dữ liệu
+- Chọn một hoặc nhiều giá trị từ danh sách dữ liệu API
 - Dropdown với tìm kiếm online/offline
-- Chọn dữ liệu dạng nhóm (group), cây (tree), JSON tree
+- Chọn dữ liệu dạng nhóm (group), cây (tree), JSON tree nested nhiều cấp
 - Cần validation (required, max items)
-- Cần điều khiển dropdown từ component cha (reset, refresh, check valid)
-- Hiển thị dropdown với tabs để phân loại dữ liệu
-- Dropdown với custom content (ng-content)
-
-## Lưu ý quan trọng
-
-- ⚠️ **Bắt buộc `[listConfig]`**: Phải cung cấp `[listConfig]` để dropdown hiển thị danh sách.
-- ⚠️ **Chế độ chọn**: Sử dụng `[listKeySelected]` cho chọn đơn (text/radio), `[listMultiKeySelected]` cho chọn nhiều (checkbox/group).
-- ⚠️ **Auto-load API**: Khi dùng `httpRequestData` trong `listConfig`, dropdown tự động gọi API để load dữ liệu.
-- ⚠️ **FunctionControl**: Output `outFunctionsControl` emit `IDropdownFunctionControlEvent` để điều khiển dropdown từ bên ngoài.
+- Cần điều khiển dropdown từ component cha (reset, refresh, check valid, set error)
+- Hiển thị dropdown với tabs để phân loại dữ liệu theo nguồn khác nhau
+- Dropdown với custom trigger (ng-content) thay vì giao diện mặc định
 
 ## Cài đặt
 
 ```bash
-# npm
 npm install @libs-ui/components-dropdown
-
-# yarn
-yarn add @libs-ui/components-dropdown
 ```
 
 ## Import
@@ -66,266 +53,676 @@ import {
 @Component({
   standalone: true,
   imports: [LibsUiComponentsDropdownComponent],
-  // ...
 })
-export class YourComponent {}
+export class MyComponent {}
+```
+
+## Ví dụ sử dụng
+
+### 1. Basic — Dropdown chọn đơn (type: text)
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { LibsUiComponentsDropdownComponent, IEmitSelectKey } from '@libs-ui/components-dropdown';
+import { IListConfigItem } from '@libs-ui/components-list';
+import { IHttpRequestConfig } from '@libs-ui/services-http-request';
+import { escapeHtml, get, set, UtilsHttpParamsRequest } from '@libs-ui/utils';
+
+@Component({
+  selector: 'app-example-basic',
+  standalone: true,
+  imports: [LibsUiComponentsDropdownComponent],
+  template: `
+    <libs_ui-components-dropdown
+      [labelConfig]="{ labelLeft: 'Chọn nhân viên', required: true }"
+      [listConfig]="listConfig"
+      [listSearchConfig]="{ noBorder: true }"
+      [listMaxItemShow]="5"
+      [convertItemSelected]="convertItemSelected"
+      [validRequired]="{}"
+      (outSelectKey)="handlerSelectKey($event)"
+      (outFunctionsControl)="handlerFunctionsControl($event)"
+    />
+  `,
+})
+export class ExampleBasicComponent {
+  private dropdownControl: IDropdownFunctionControlEvent | undefined;
+
+  readonly listConfig: IListConfigItem = {
+    type: 'text',
+    httpRequestData: signal<IHttpRequestConfig>({
+      objectInstance: myApiService,
+      functionName: 'getList',
+      argumentsValue: [new UtilsHttpParamsRequest({ fromObject: { page: 1, per_page: 20 } })],
+    }),
+    configTemplateText: signal({
+      fieldKey: 'id',
+      notUseVirtualScroll: true,
+      getValue: (item: { name: string }) => escapeHtml(item.name),
+    }),
+  };
+
+  readonly convertItemSelected = (item: unknown): void => {
+    if (!item) return;
+    set(item as Record<string, unknown>, 'labelDisplay', escapeHtml(get(item as Record<string, string>, 'name') || ''));
+  };
+
+  handlerSelectKey(event: IEmitSelectKey | undefined): void {
+    event?.key; // id item đã chọn
+    event?.item; // object item đầy đủ
+  }
+
+  handlerFunctionsControl(event: IDropdownFunctionControlEvent): void {
+    this.dropdownControl = event;
+  }
+
+  async resetSelection(): Promise<void> {
+    await this.dropdownControl?.reset();
+  }
+}
+```
+
+### 2. Dropdown chọn nhiều (type: checkbox)
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { LibsUiComponentsDropdownComponent, IEmitMultiKey } from '@libs-ui/components-dropdown';
+import { IListConfigItem } from '@libs-ui/components-list';
+import { IHttpRequestConfig } from '@libs-ui/services-http-request';
+import { escapeHtml, get, set, UtilsHttpParamsRequest } from '@libs-ui/utils';
+
+@Component({
+  selector: 'app-example-checkbox',
+  standalone: true,
+  imports: [LibsUiComponentsDropdownComponent],
+  template: `
+    <libs_ui-components-dropdown
+      [labelConfig]="{ labelLeft: 'Chọn nhiều nhãn', required: true }"
+      [listConfig]="checkboxConfig"
+      [listSearchConfig]="{ noBorder: true }"
+      [listMaxItemShow]="5"
+      [(listMultiKeySelected)]="selectedKeys"
+      [convertItemSelected]="convertItemSelected"
+      [validRequired]="{}"
+      [validMaxItemSelected]="{ value: 3, message: 'Chỉ được chọn tối đa 3 mục' }"
+      (outSelectMultiKey)="handlerSelectMultiKey($event)"
+    />
+  `,
+})
+export class ExampleCheckboxComponent {
+  selectedKeys = signal<string[]>([]);
+
+  readonly checkboxConfig: IListConfigItem = {
+    type: 'checkbox',
+    httpRequestData: signal<IHttpRequestConfig>({
+      objectInstance: myApiService,
+      functionName: 'getList',
+      argumentsValue: [new UtilsHttpParamsRequest({ fromObject: { page: 1, per_page: 20 } })],
+    }),
+    autoSelectFirstItem: false,
+    configTemplateCheckbox: signal({
+      fieldKey: 'id',
+      configButtonSelectAndUndSelectItem: signal({}),
+      getValue: (item: { name: string }) => escapeHtml(item.name),
+    }),
+  };
+
+  readonly convertItemSelected = (item: unknown): void => {
+    if (!item) return;
+    set(item as Record<string, unknown>, 'labelDisplay', escapeHtml(get(item as Record<string, string>, 'name') || ''));
+  };
+
+  handlerSelectMultiKey(event: IEmitMultiKey | undefined): void {
+    event?.keys;    // mảng id đã chọn
+    event?.mapKeys; // mảng { key, item } đầy đủ
+  }
+}
 ```
 
-## Ví dụ
+### 3. Dropdown dạng nhóm — Group Checkbox
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { LibsUiComponentsDropdownComponent, IEmitMultiKey } from '@libs-ui/components-dropdown';
+import { IListConfigItem } from '@libs-ui/components-list';
+import { IHttpRequestConfig, returnListObject } from '@libs-ui/services-http-request';
+import { escapeHtml, get, set } from '@libs-ui/utils';
+
+@Component({
+  selector: 'app-example-group',
+  standalone: true,
+  imports: [LibsUiComponentsDropdownComponent],
+  template: `
+    <libs_ui-components-dropdown
+      [labelConfig]="{ labelLeft: 'Chọn theo nhóm', required: true }"
+      [listConfig]="groupConfig"
+      [listMaxItemShow]="5"
+      [convertItemSelected]="convertItemSelected"
+      (outSelectMultiKey)="handlerSelectMultiKey($event)"
+    />
+  `,
+})
+export class ExampleGroupComponent {
+  private readonly groupDataService = returnListObject([
+    {
+      id: 'nhom_a',
+      name: 'Nhóm A',
+      items: [
+        { id: 'a1', name: 'Mục A1' },
+        { id: 'a2', name: 'Mục A2' },
+      ],
+    },
+    {
+      id: 'nhom_b',
+      name: 'Nhóm B',
+      items: [{ id: 'b1', name: 'Mục B1' }],
+    },
+  ]);
+
+  readonly groupConfig: IListConfigItem = {
+    type: 'group',
+    httpRequestData: signal<IHttpRequestConfig>({
+      objectInstance: this.groupDataService,
+      functionName: 'list',
+      argumentsValue: [],
+    }),
+    configTemplateGroup: signal({
+      fieldKey: 'id',
+      fieldGetItems: 'items',
+      getLabelGroup: (group: { name: string }) => escapeHtml(group.name),
+      getMaxLevelGroup: () => 2,
+      getLabelItem: (item: { name: string }) => escapeHtml(item.name),
+      iconExpand: 'right',
+      isViewRadio: false,
+    }),
+  };
+
+  readonly convertItemSelected = (item: unknown): void => {
+    if (!item) return;
+    set(item as Record<string, unknown>, 'labelDisplay', escapeHtml(get(item as Record<string, string>, 'name') || ''));
+  };
+
+  handlerSelectMultiKey(event: IEmitMultiKey | undefined): void {
+    event?.keys;
+  }
+}
+```
 
-### Basic - Text
+### 4. Dropdown Group Radio — chọn đơn trong nhóm
 
 ```html
 <libs_ui-components-dropdown
-  [labelConfig]="{ labelLeft: 'Chọn item', required: true }"
-  [listConfig]="listConfig"
-  [listSearchConfig]="{ noBorder: true }"
+  [labelConfig]="{ labelLeft: 'Chọn một mục trong nhóm', required: true }"
+  [listConfig]="groupRadioConfig"
   [listMaxItemShow]="5"
   [convertItemSelected]="convertItemSelected"
-  (outSelectKey)="onSelectKey($event)"
+  (outSelectKey)="handlerSelectKey($event)"
 />
 ```
 
 ```typescript
-listConfig: IListConfigItem = {
-  type: 'text',
-  httpRequestData: signal<IHttpRequestConfig>({
-    objectInstance: getConfigListDataDemo(),
-    functionName: 'list',
-    argumentsValue: [new UtilsHttpParamsRequest({ fromObject: { page: 1, per_page: 20 } })],
-  }),
-  configTemplateText: signal({
+readonly groupRadioConfig: IListConfigItem = {
+  type: 'group',
+  httpRequestData: signal<IHttpRequestConfig>(groupHttpConfig),
+  configTemplateGroup: signal({
     fieldKey: 'id',
-    notUseVirtualScroll: true,
-    getValue: (item) => escapeHtml(item.name),
+    fieldGetItems: 'items',
+    getLabelGroup: (group: { name: string }) => escapeHtml(group.name),
+    getMaxLevelGroup: () => 2,
+    getLabelItem: (item: { name: string }) => escapeHtml(item.name),
+    iconExpand: 'right',
+    isViewRadio: true, // chỉ khác group checkbox ở dòng này
   }),
 };
 ```
 
-### Checkbox
+### 5. Dropdown Radio
 
 ```html
 <libs_ui-components-dropdown
-  [labelConfig]="{ labelLeft: 'Chọn nhiều (checkbox)', required: true }"
-  [listConfig]="checkboxConfig"
+  [labelConfig]="{ labelLeft: 'Chọn loại khách hàng', required: true }"
+  [listConfig]="radioConfig"
   [listMaxItemShow]="5"
   [convertItemSelected]="convertItemSelected"
-  (outSelectMultiKey)="onSelectMultiKey($event)"
+  (outSelectKey)="handlerSelectKey($event)"
 />
 ```
 
-### Radio
-
-```html
-<libs_ui-components-dropdown
-  [labelConfig]="{ labelLeft: 'Chọn item (radio)', required: true }"
-  [listConfig]="radioConfig"
-  [listMaxItemShow]="5"
-  [convertItemSelected]="convertItemSelected"
-  (outSelectKey)="onSelectKey($event)"
-/>
+```typescript
+readonly radioConfig: IListConfigItem = {
+  type: 'radio',
+  httpRequestData: signal<IHttpRequestConfig>({
+    objectInstance: myApiService,
+    functionName: 'getList',
+    argumentsValue: [new UtilsHttpParamsRequest({ fromObject: { page: 1, per_page: 20 } })],
+  }),
+  configTemplateRadio: signal({
+    fieldKey: 'id',
+    getValue: (item: { name: string }) => escapeHtml(item.name),
+  }),
+};
 ```
 
-### Interactive - Controls
+### 6. Dropdown với FunctionControl — điều khiển từ bên ngoài
 
 ```html
+<div class="flex gap-[8px] mb-[16px]">
+  <button (click)="handlerReset()">Reset</button>
+  <button (click)="handlerCheckValid()">Check Valid</button>
+  <button (click)="handlerRefresh()">Refresh</button>
+  <button (click)="handlerSetError()">Set Error</button>
+</div>
+
 <libs_ui-components-dropdown
-  [labelConfig]="{ labelLeft: 'Interactive', required: true }"
+  [labelConfig]="{ labelLeft: 'Dropdown có điều khiển', required: true }"
   [listConfig]="listConfig"
   [listMaxItemShow]="5"
   [validRequired]="{}"
-  (outFunctionsControl)="onFunctionControl($event)"
+  (outFunctionsControl)="handlerFunctionsControl($event)"
+  (outValidEvent)="handlerValidEvent($event)"
 />
 ```
 
 ```typescript
-dropdownControl: IDropdownFunctionControlEvent | undefined;
+import { IDropdownFunctionControlEvent, IEmitSelectKey } from '@libs-ui/components-dropdown';
+
+private dropdownControl: IDropdownFunctionControlEvent | undefined;
 
-onFunctionControl(event: IDropdownFunctionControlEvent) {
+handlerFunctionsControl(event: IDropdownFunctionControlEvent): void {
   this.dropdownControl = event;
 }
 
-async resetDropdown() {
+handlerValidEvent(isValid: boolean): void {
+  // true khi hợp lệ, false khi có lỗi validation
+}
+
+async handlerReset(): Promise<void> {
   await this.dropdownControl?.reset();
 }
 
-async checkValid() {
+async handlerCheckValid(): Promise<void> {
   const isValid = await this.dropdownControl?.checkIsValid();
-  console.log('Valid:', isValid);
+  // isValid: true/false
 }
 
-async refreshList() {
+async handlerRefresh(): Promise<void> {
   await this.dropdownControl?.refreshList();
 }
+
+async handlerSetError(): Promise<void> {
+  await this.dropdownControl?.setError?.('i18n_error_message');
+}
+
+async handlerSetItemByKey(): Promise<void> {
+  await this.dropdownControl?.setItemSelectedByKey('abc-123');
+}
+
+async handlerUpdateLabel(): Promise<void> {
+  await this.dropdownControl?.updateLabelItemSelected('Tên hiển thị mới');
+}
+```
+
+### 7. Dropdown với Tabs phân loại dữ liệu
+
+```typescript
+import { IDropdownTabsItem } from '@libs-ui/components-dropdown';
+
+readonly tabsConfig: IDropdownTabsItem[] = [
+  {
+    key: 'all',
+    name: 'Tất cả',
+    httpRequestData: {
+      objectInstance: allApiService,
+      functionName: 'getList',
+      argumentsValue: [],
+    },
+  },
+  {
+    key: 'active',
+    name: 'Hoạt động',
+    httpRequestData: {
+      objectInstance: activeApiService,
+      functionName: 'getList',
+      argumentsValue: [],
+    },
+  },
+];
+```
+
+```html
+<libs_ui-components-dropdown
+  [labelConfig]="{ labelLeft: 'Chọn với tab phân loại', required: true }"
+  [listConfig]="listConfig"
+  [tabsConfig]="tabsConfig"
+  [(tabKeyActive)]="activeTabKey"
+  [listMaxItemShow]="5"
+  [convertItemSelected]="convertItemSelected"
+  (outSelectKey)="handlerSelectKey($event)"
+  (outChangeTabKeyActive)="handlerChangeTab($event)"
+/>
+```
+
+```typescript
+protected activeTabKey = signal<string>('all');
+
+handlerChangeTab(key: string | undefined): void {
+  // key: tab vừa được chọn
+}
 ```
 
-### States
+### 8. Dropdown trạng thái: Disable / Readonly / Validation
 
 ```html
 <!-- Disable -->
 <libs_ui-components-dropdown
-  [labelConfig]="{ labelLeft: 'Disable' }"
-  [disable]="true"
+  [labelConfig]="{ labelLeft: 'Trạng thái disable' }"
   [listConfig]="listConfig"
+  [disable]="true"
 />
 
 <!-- Readonly -->
 <libs_ui-components-dropdown
-  [labelConfig]="{ labelLeft: 'Readonly' }"
+  [labelConfig]="{ labelLeft: 'Trạng thái readonly' }"
+  [listConfig]="listConfig"
   [readonly]="true"
+  [(listKeySelected)]="selectedKey"
+/>
+
+<!-- Validation required -->
+<libs_ui-components-dropdown
+  [labelConfig]="{ labelLeft: 'Bắt buộc chọn', required: true }"
+  [listConfig]="listConfig"
+  [validRequired]="{ message: 'i18n_field_required' }"
+  [showError]="true"
+/>
+
+<!-- Validation max items -->
+<libs_ui-components-dropdown
+  [labelConfig]="{ labelLeft: 'Chọn tối đa 3', required: true }"
+  [listConfig]="checkboxConfig"
+  [validMaxItemSelected]="{ value: 3, message: 'Chỉ được chọn tối đa {value} mục', interpolateParams: { value: 3 } }"
+/>
+```
+
+### 9. Dropdown với tìm kiếm online (Search Online)
+
+```html
+<libs_ui-components-dropdown
+  [labelConfig]="{ labelLeft: 'Tìm kiếm online', required: true }"
+  [listConfig]="listConfig"
+  [isSearchOnline]="true"
+  [listSearchConfig]="{ noBorder: true, placeholder: 'Gõ keyword để tìm kiếm...' }"
+  [listMaxItemShow]="8"
+  [convertItemSelected]="convertItemSelected"
+  (outSelectKey)="handlerSelectKey($event)"
+/>
+```
+
+### 10. Dropdown lazy-load chi tiết item theo key
+
+Dùng khi dropdown chỉ nhận được key (id) từ server, cần gọi API riêng để lấy thông tin hiển thị.
+
+> 🔴 **Lỗi phổ biến:** Truyền `[(listKeySelected)]="selectedKey"` (key có sẵn) **NHƯNG quên** `[httpRequestDetailItemById]`. Dropdown chỉ có key, không có item → label hiển thị trắng. BẮT BUỘC cấu hình `[httpRequestDetailItemById]` như ví dụ dưới.
+
+```html
+<!-- ❌ SAI — có key nhưng thiếu httpRequestDetailItemById → label trắng -->
+<libs_ui-components-dropdown
+  [labelConfig]="{ labelLeft: 'Thiếu detail config' }"
+  [listConfig]="listConfig"
+  [(listKeySelected)]="selectedKey"
+  [convertItemSelected]="convertItemSelected"
+/>
+```
+
+```html
+<!-- ✅ ĐÚNG -->
+<libs_ui-components-dropdown
+  [labelConfig]="{ labelLeft: 'Dropdown lazy-load detail' }"
+  [listConfig]="listConfig"
+  [(listKeySelected)]="selectedKey"
+  [httpRequestDetailItemById]="httpRequestDetailConfig"
+  [convertItemSelected]="convertItemSelected"
+  (outSelectKey)="handlerSelectKey($event)"
+/>
+```
+
+```typescript
+readonly httpRequestDetailConfig: IHttpRequestConfig = {
+  objectInstance: detailApiService,
+  functionName: 'getDetailByKey',
+  argumentsValue: [],
+  guideAutoUpdateArgumentsValue: {
+    paging: {},
+    detailById: {
+      fieldGetValue: '',
+      fieldUpdate: '[0]',
+    },
+  },
+};
+
+selectedKey = signal<string>('item-id-123'); // sẽ tự gọi API để load tên hiển thị
+```
+
+### 11. Dropdown không load list trước khi search
+
+```html
+<libs_ui-components-dropdown
+  [labelConfig]="{ labelLeft: 'Gõ keyword để bắt đầu load' }"
+  [listConfig]="listConfig"
+  [isSearchOnline]="true"
+  [listHiddenInputSearch]="false"
+  [listSearchConfig]="{ noBorder: true, placeholder: 'Nhập để tìm kiếm...' }"
+  [dropdownIgnoreNotSearch]="true"
+/>
+```
+
+### 12. Dropdown với Custom Popover Config
+
+```typescript
+import { IPopoverCustomConfig } from '@libs-ui/components-dropdown';
+
+readonly popoverConfig: IPopoverCustomConfig = {
+  widthByParent: false,
+  maxWidth: 500,
+  maxHeight: 400,
+  direction: 'bottom',
+  ignoreArrow: true,
+  position: { mode: 'start', distance: 0 },
+  animationConfig: { time: 200, distance: 8 },
+};
+```
+
+```html
+<libs_ui-components-dropdown
+  [labelConfig]="{ labelLeft: 'Dropdown custom popover' }"
   [listConfig]="listConfig"
+  [popoverCustomConfig]="popoverConfig"
+  [zIndex]="1050"
+  [convertItemSelected]="convertItemSelected"
+  (outSelectKey)="handlerSelectKey($event)"
 />
 ```
 
-## API
-
-### libs_ui-components-dropdown
-
-#### Inputs
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `[allowSelectItemMultiple]` | `boolean` | `undefined` | Cho phép chọn lại item đã chọn |
-| `[changeValidUndefinedResetError]` | `boolean` | `undefined` | Reset error khi valid undefined |
-| `[classAvatarInclude]` | `string` | `'mr-[8px]'` | Class CSS cho avatar |
-| `[classInclude]` | `string` | `undefined` | Class CSS bổ sung cho container |
-| `[classIncludeContent]` | `string` | `undefined` | Class CSS cho content wrapper |
-| `[classIncludeIcon]` | `string` | `'ml-[8px]'` | Class CSS cho icon mũi tên |
-| `[classIncludeTextDisplayWhenNoSelect]` | `string` | `'libs-ui-font-h5r'` | Class CSS cho text placeholder |
-| `[convertItemSelected]` | `(item, translate?) => void` | `defaultConvert` | Hàm convert item sau khi chọn để hiển thị label |
-| `[disable]` | `boolean` | `undefined` | Vô hiệu hóa dropdown |
-| `[disableLabel]` | `boolean` | `undefined` | Vô hiệu hóa label |
-| `[fieldGetColorAvatar]` | `string` | `undefined` | Field lấy color cho avatar |
-| `[fieldGetIcon]` | `string` | `undefined` | Field lấy icon class từ item |
-| `[fieldGetImage]` | `string` | `undefined` | Field lấy URL ảnh từ item |
-| `[fieldGetLabel]` | `string` | `undefined` | Field lấy label từ item |
-| `[fieldGetTextAvatar]` | `string` | `'username'` | Field lấy text cho avatar |
-| `[fieldLabel]` | `string` | `'labelDisplay'` | Field lưu label hiển thị trên dropdown |
-| `[flagMouse]` | `IFlagMouse (model)` | `{ isMouseEnter: false, isMouseEnterContent: false }` | Trạng thái mouse |
-| `[flagMouseContent]` | `IFlagMouse (model)` | `undefined` | Trạng thái mouse content |
-| `[focusInputSearch]` | `boolean` | `true` | Tự động focus input tìm kiếm khi mở |
-| `[getLastTextAfterSpace]` | `boolean` | `undefined` | Lấy text cuối sau dấu cách |
-| `[getPopoverItemSelected]` | `(item, translate?) => Promise<IPopover>` | `undefined` | Hàm lấy popover config cho item đã chọn |
-| `[hasContentUnitRight]` | `boolean` | `undefined` | Có content bên phải unit |
-| `[httpRequestDetailItemById]` | `IHttpRequestConfig` | `undefined` | Config HTTP request để lấy chi tiết item theo key |
-| `[ignoreBorderBottom]` | `boolean` | `undefined` | Bỏ border bottom |
-| `[ignoreStopPropagationEvent]` | `boolean` | `false` | Bỏ qua stopPropagation |
-| `[imageSize]` | `TYPE_SIZE_AVATAR_CONFIG` | `16` | Kích thước avatar |
-| `[isNgContent]` | `boolean` | `undefined` | Sử dụng ng-content thay vì giao diện mặc định |
-| `[isSearchOnline]` | `boolean` | `false` | Tìm kiếm online (gọi API) |
-| `[labelConfig]` | `ILabel` | `undefined` | Cấu hình label phía trên dropdown |
-| `[labelPopoverConfig]` | `IPopoverOverlay` | `undefined` | Config popover cho label |
-| `[labelPopoverFullWidth]` | `boolean` | `true` | Popover label full width |
-| `[lengthKeys]` | `number (model)` | `0` | Số lượng keys đã chọn |
-| `[linkImageError]` | `string` | `undefined` | Link ảnh khi lỗi |
-| `[listBackgroundCustom]` | `string` | `undefined` | Background custom cho list |
-| `[listButtonsOther]` | `Array<IButton>` | `undefined` | Các button khác trong list |
-| `[listClickExactly]` | `boolean` | `undefined` | Click chính xác item |
-| `[listConfig]` | `IListConfigItem` | `undefined` | Cấu hình danh sách (type, httpRequestData, template config) |
-| `[listConfigHasDivider]` | `boolean` | `true` | Hiển thị divider trong list |
-| `[listDividerClassInclude]` | `string` | `undefined` | Class CSS cho divider |
-| `[listHasButtonUnSelectOption]` | `boolean` | `undefined` | Hiển thị nút bỏ chọn |
-| `[listHiddenInputSearch]` | `boolean` | `undefined` | Ẩn input tìm kiếm |
-| `[listIgnoreClassDisableDefaultWhenUseKeysDisableItem]` | `boolean` | `undefined` | Bỏ class disable mặc định khi dùng keysDisable |
-| `[listKeysDisable]` | `Array<string>` | `undefined` | Danh sách keys bị disable |
-| `[listKeysHidden]` | `Array<string>` | `undefined` | Danh sách keys bị ẩn |
-| `[listKeySearch]` | `string` | `undefined` | Key tìm kiếm |
-| `[listKeySelected]` | `unknown (model)` | `undefined` | Key item đang được chọn (single select) |
-| `[listMaxItemShow]` | `number` | `5` | Số item tối đa hiển thị |
-| `[listMultiKeySelected]` | `Array<unknown> (model)` | `undefined` | Danh sách keys đang được chọn (multi select) |
-| `[listSearchConfig]` | `IInputSearchConfig` | `{ noBorder: true }` | Cấu hình input tìm kiếm |
-| `[listSearchNoDataTemplateRef]` | `TemplateRef<unknown>` | `undefined` | Template khi không có dữ liệu tìm kiếm |
-| `[listSearchPadding]` | `boolean` | `undefined` | Padding cho search |
-| `[onlyEmitDataWhenReset]` | `boolean` | `undefined` | Chỉ emit sự kiện khi reset |
-| `[popoverCustomConfig]` | `IPopoverCustomConfig` | `undefined` | Cấu hình popover overlay |
-| `[popoverElementRefCustom]` | `HTMLElement` | `undefined` | Element ref custom cho popover |
-| `[readonly]` | `boolean` | `undefined` | Chế độ chỉ đọc |
-| `[resetKeyWhenSelectAllKey]` | `boolean` | `undefined` | Reset key khi select all |
-| `[showBorderError]` | `boolean (model)` | `undefined` | Hiển thị border error |
-| `[showError]` | `boolean` | `true` | Hiển thị error message |
-| `[tabKeyActive]` | `string (model)` | `undefined` | Key tab đang active |
-| `[tabsConfig]` | `Array<IDropdownTabsItem>` | `undefined` | Cấu hình tabs cho dropdown |
-| `[textDisplayWhenMultiSelect]` | `string` | `'i18n_selecting_options'` | Text hiển thị khi chọn nhiều |
-| `[textDisplayWhenNoSelect]` | `string` | `'i18n_select_information'` | Text hiển thị khi chưa chọn |
-| `[typeShape]` | `TYPE_SHAPE_AVATAR` | `'circle'` | Hình dạng avatar |
-| `[useXssFilter]` | `boolean` | `false` | Bật XSS filter |
-| `[validMaxItemSelected]` | `IValidMaxItemSelected` | `undefined` | Validation số item chọn tối đa |
-| `[validRequired]` | `IMessageTranslate` | `undefined` | Validation required |
-| `[zIndex]` | `number` | `undefined` | z-index cho popover |
-
-#### Outputs
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `(outChangStageFlagMouse)` | `IFlagMouse` | Emit khi trạng thái mouse thay đổi |
-| `(outChangeTabKeyActive)` | `string \| undefined` | Emit khi tab active thay đổi |
-| `(outClickButtonOther)` | `IButton` | Emit khi click button khác trong list |
-| `(outDataChange)` | `Array<unknown>` | Emit khi dữ liệu list thay đổi |
-| `(outFunctionsControl)` | `IDropdownFunctionControlEvent` | Emit functions để điều khiển dropdown |
-| `(outSelectKey)` | `IEmitSelectKey \| undefined` | Emit khi chọn item (single select) |
-| `(outSelectMultiKey)` | `IEmitMultiKey \| undefined` | Emit khi chọn items (multi select) |
-| `(outShowList)` | `boolean` | Emit khi show/hide list |
-| `(outValidEvent)` | `boolean` | Emit kết quả validation |
-
-#### FunctionControl Methods
-
-| Method | Description |
-|--------|-------------|
-| `checkIsValid()` | Kiểm tra validation và trả về boolean |
-| `getDisable()` | Lấy trạng thái disable |
-| `refreshList()` | Refresh lại danh sách dữ liệu |
-| `removeList()` | Đóng popup danh sách |
-| `reset()` | Reset dropdown về trạng thái ban đầu |
-| `resetError()` | Xóa error hiện tại |
-| `setError(message)` | Đặt error message |
-| `setItemSelectedByKey(id)` | Chọn item theo key (gọi API nếu có httpRequestDetailItemById) |
-| `updateLabelItemSelected(label)` | Cập nhật label của item đã chọn |
+## @Input()
+
+| Input | Type | Default | Mô tả | Ví dụ |
+|---|---|---|---|---|
+| `[allowSelectItemMultiple]` | `boolean` | `undefined` | Cho phép chọn lại item đã chọn dù key không đổi | `[allowSelectItemMultiple]="true"` |
+| `[changeValidUndefinedResetError]` | `boolean` | `undefined` | Tự động reset error khi `validRequired` thay đổi về undefined | `[changeValidUndefinedResetError]="true"` |
+| `[classAvatarInclude]` | `string` | `'mr-[8px]'` | Class CSS bổ sung cho avatar hiển thị bên trái label | `[classAvatarInclude]="'mr-[4px]'"` |
+| `[classInclude]` | `string` | `undefined` | Class CSS bổ sung cho wrapper ngoài cùng của dropdown | `[classInclude]="'w-[300px]'"` |
+| `[classIncludeContent]` | `string` | `undefined` | Class CSS bổ sung cho phần trigger content (box hiển thị item đã chọn) | `[classIncludeContent]="'h-[40px]'"` |
+| `[classIncludeIcon]` | `string` | `'ml-[8px]'` | Class CSS bổ sung cho icon mũi tên bên phải | `[classIncludeIcon]="'ml-[4px]'"` |
+| `[classIncludeTextDisplayWhenNoSelect]` | `string` | `'libs-ui-font-h5r'` | Class CSS cho text placeholder khi chưa chọn | `[classIncludeTextDisplayWhenNoSelect]="'libs-ui-font-h5m'"` |
+| `[convertItemSelected]` | `(item: unknown, translate?: TranslateService) => void` | `defaultConvert` | Hàm chuyển đổi item đã chọn để lấy label hiển thị vào field `labelDisplay` | `[convertItemSelected]="convertFn"` |
+| `[disable]` | `boolean` | `undefined` | Vô hiệu hóa dropdown, không cho tương tác | `[disable]="true"` |
+| `[disableLabel]` | `boolean` | `undefined` | Vô hiệu hóa label phía trên dropdown | `[disableLabel]="true"` |
+| `[dropdownTemplateRefNotSearchNoData]` | `TemplateRef<TYPE_TEMPLATE_REF>` | `undefined` | Template custom cho trạng thái "chưa search" hoặc empty state | `[dropdownTemplateRefNotSearchNoData]="myTemplate"` |
+| `[fieldGetColorAvatar]` | `string` | `undefined` | Tên field lấy màu nền cho avatar từ item | `[fieldGetColorAvatar]="'color'"` |
+| `[fieldGetIcon]` | `string` | `undefined` | Tên field lấy class icon từ item để hiển thị bên trái label | `[fieldGetIcon]="'iconClass'"` |
+| `[fieldGetImage]` | `string` | `undefined` | Tên field lấy URL ảnh avatar từ item | `[fieldGetImage]="'avatar_url'"` |
+| `[fieldGetLabel]` | `string` | `undefined` | Tên field lấy label từ item (override mặc định `label`/`name`) | `[fieldGetLabel]="'full_name'"` |
+| `[fieldGetTextAvatar]` | `string` | `'username'` | Tên field lấy text để render avatar chữ | `[fieldGetTextAvatar]="'name'"` |
+| `[fieldLabel]` | `string` | `'labelDisplay'` | Tên field lưu label hiển thị sau khi `convertItemSelected` chạy | `[fieldLabel]="'displayName'"` |
+| `[flagMouse]` | `IFlagMouse` (model) | `{ isMouseEnter: false, isMouseEnterContent: false }` | Two-way binding trạng thái chuột vào/ra dropdown trigger | `[(flagMouse)]="flagMouse"` |
+| `[flagMouseContent]` | `IFlagMouse` (model) | `undefined` | Two-way binding trạng thái chuột vào/ra vùng nội dung popover | `[(flagMouseContent)]="flagMouseContent"` |
+| `[focusInputSearch]` | `boolean` | `true` | Tự động focus vào input tìm kiếm khi mở dropdown | `[focusInputSearch]="false"` |
+| `[getLastTextAfterSpace]` | `boolean` | `undefined` | Lấy phần text sau khoảng trắng cuối cùng để hiển thị lên avatar | `[getLastTextAfterSpace]="true"` |
+| `[getPopoverItemSelected]` | `(item, translate?) => Promise<IPopover \| undefined>` | `undefined` | Hàm async trả về config popover hiển thị khi hover item đã chọn | `[getPopoverItemSelected]="getPopoverFn"` |
+| `[hasContentUnitRight]` | `boolean` | `undefined` | Bỏ border-radius góc phải để ghép với unit bên phải | `[hasContentUnitRight]="true"` |
+| `[httpRequestDetailItemById]` | `IHttpRequestConfig` | `undefined` | Config HTTP request để lazy-load chi tiết item theo key khi chọn | `[httpRequestDetailItemById]="detailConfig"` |
+| `[ignoreBorderBottom]` | `boolean` | `undefined` | Ẩn border bottom của tabs header | `[ignoreBorderBottom]="true"` |
+| `[ignoreStopPropagationEvent]` | `boolean` | `false` | Bỏ qua `stopPropagation` khi click trigger | `[ignoreStopPropagationEvent]="true"` |
+| `[imageSize]` | `TYPE_SIZE_AVATAR_CONFIG` | `16` | Kích thước avatar hiển thị (pixel) | `[imageSize]="24"` |
+| `[isNgContent]` | `boolean` | `undefined` | Dùng `ng-content` làm trigger thay vì giao diện mặc định | `[isNgContent]="true"` |
+| `[isSearchOnline]` | `boolean` | `false` | Gọi API mỗi lần thay đổi từ khóa tìm kiếm (search online) | `[isSearchOnline]="true"` |
+| `[labelConfig]` | `ILabel` | `undefined` | Cấu hình label phía trên dropdown (labelLeft, required, description, buttons...) | `[labelConfig]="{ labelLeft: 'Tên', required: true }"` |
+| `[labelPopoverConfig]` | `IPopoverOverlay` | `undefined` | Config popover tooltip cho label hiển thị item đã chọn | `[labelPopoverConfig]="{ maxWidth: 300 }"` |
+| `[labelPopoverFullWidth]` | `boolean` | `true` | Label popover chiếm full width | `[labelPopoverFullWidth]="false"` |
+| `[lengthKeys]` | `number` (model) | `0` | Two-way binding số lượng key đã chọn | `[(lengthKeys)]="selectedCount"` |
+| `[linkImageError]` | `string` | `undefined` | URL ảnh fallback khi ảnh avatar bị lỗi | `[linkImageError]="'/assets/default.png'"` |
+| `[listBackgroundCustom]` | `string` | `undefined` | Background color custom cho danh sách | `[listBackgroundCustom]="'#f5f5f5'"` |
+| `[listButtonsOther]` | `Array<IButton>` | `undefined` | Các button bổ sung hiển thị ở cuối danh sách | `[listButtonsOther]="extraButtons"` |
+| `[listClickExactly]` | `boolean` | `undefined` | Chỉ phản hồi click chính xác vào item (không phải vùng padding) | `[listClickExactly]="true"` |
+| `[listConfig]` | `IListConfigItem` | `undefined` | **Bắt buộc.** Cấu hình danh sách (type, httpRequestData, template config) | `[listConfig]="myListConfig"` |
+| `[listConfigHasDivider]` | `boolean` | `true` | Hiển thị đường divider trong danh sách | `[listConfigHasDivider]="false"` |
+| `[listDividerClassInclude]` | `string` | `undefined` | Class CSS bổ sung cho đường divider | `[listDividerClassInclude]="'my-[4px]'"` |
+| `[listHasButtonUnSelectOption]` | `boolean` | `auto` | Hiển thị nút "Bỏ chọn" trong danh sách | `[listHasButtonUnSelectOption]="true"` |
+| `[listHiddenInputSearch]` | `boolean` | `undefined` | Ẩn input tìm kiếm | `[listHiddenInputSearch]="true"` |
+| `[listIgnoreClassDisableDefaultWhenUseKeysDisableItem]` | `boolean` | `undefined` | Bỏ class style disable mặc định khi dùng `listKeysDisable` (để tự xử lý styling) | `[listIgnoreClassDisableDefaultWhenUseKeysDisableItem]="true"` |
+| `[listKeysDisable]` | `Array<string>` | `undefined` | Danh sách key của item bị vô hiệu hóa trong list (không cho chọn) | `[listKeysDisable]="['id1', 'id2']"` |
+| `[listKeysHidden]` | `Array<string>` | `undefined` | Danh sách key của item bị ẩn trong list | `[listKeysHidden]="['id3']"` |
+| `[listKeySearch]` | `string` | `undefined` | Tên field dùng để tìm kiếm trong danh sách (mặc định dùng field label) | `[listKeySearch]="'name'"` |
+| `[(listKeySelected)]` | `unknown` (model) | `undefined` | Two-way binding key item đang được chọn (chọn đơn) | `[(listKeySelected)]="selectedId"` |
+| `[listMaxItemShow]` | `number` | `5` | Số item tối đa hiển thị trong danh sách trước khi cuộn (`-1` = không giới hạn) | `[listMaxItemShow]="8"` |
+| `[(listMultiKeySelected)]` | `Array<unknown>` (model) | `undefined` | Two-way binding mảng key đang được chọn (chọn nhiều) | `[(listMultiKeySelected)]="selectedIds"` |
+| `[listSearchConfig]` | `IInputSearchConfig` | `{ noBorder: true }` | Cấu hình input tìm kiếm (placeholder, noBorder...) | `[listSearchConfig]="{ noBorder: true, placeholder: 'Tìm kiếm...' }"` |
+| `[listSearchNoDataTemplateRef]` | `TemplateRef<unknown>` | `undefined` | Template khi tìm kiếm không có kết quả | `[listSearchNoDataTemplateRef]="noDataTpl"` |
+| `[listSearchPadding]` | `boolean` | `undefined` | Thêm padding cho phần search | `[listSearchPadding]="true"` |
+| `[onlyEmitDataWhenReset]` | `boolean` | `undefined` | Chỉ emit `outSelectKey`/`outSelectMultiKey` (với undefined) khi gọi `reset()` | `[onlyEmitDataWhenReset]="true"` |
+| `[popoverCustomConfig]` | `IPopoverCustomConfig` | `undefined` | Cấu hình tùy chỉnh cho popover overlay (width, direction, maxHeight...) | `[popoverCustomConfig]="popoverConfig"` |
+| `[popoverElementRefCustom]` | `HTMLElement` | `undefined` | Element HTML tùy chỉnh làm anchor cho popover | `[popoverElementRefCustom]="myEl"` |
+| `[readonly]` | `boolean` | `undefined` | Chế độ chỉ đọc (hiển thị nhưng không cho tương tác) | `[readonly]="true"` |
+| `[resetKeyWhenSelectAllKey]` | `boolean` | `undefined` | Reset key đã chọn khi checkbox "Chọn tất cả" được nhấn | `[resetKeyWhenSelectAllKey]="true"` |
+| `[(showBorderError)]` | `boolean` (model) | `undefined` | Two-way binding hiển thị border màu đỏ (lỗi) | `[(showBorderError)]="hasError"` |
+| `[showError]` | `boolean` | `true` | Hiển thị thông báo lỗi validation dưới dropdown | `[showError]="false"` |
+| `[(tabKeyActive)]` | `string` (model) | `undefined` | Two-way binding key của tab đang active | `[(tabKeyActive)]="activeTab"` |
+| `[tabsConfig]` | `Array<IDropdownTabsItem>` | `undefined` | Cấu hình tabs hiển thị phía trên danh sách | `[tabsConfig]="tabsConfig"` |
+| `[textDisplayWhenMultiSelect]` | `string` | `'i18n_selecting_options'` | Text hiển thị khi chọn nhiều hơn 1 item | `[textDisplayWhenMultiSelect]="'i18n_selected_count'"` |
+| `[textDisplayWhenNoSelect]` | `string` | `'i18n_select_information'` | Text placeholder hiển thị khi chưa chọn item nào | `[textDisplayWhenNoSelect]="'i18n_choose_option'"` |
+| `[typeShape]` | `TYPE_SHAPE_AVATAR` | `'circle'` | Hình dạng của avatar (`'circle'` hoặc `'square'`) | `[typeShape]="'square'"` |
+| `[useXssFilter]` | `boolean` | `false` | Bật XSS filter cho nội dung label hiển thị | `[useXssFilter]="true"` |
+| `[validMaxItemSelected]` | `IValidMaxItemSelected` | `undefined` | Cấu hình validation giới hạn số item chọn tối đa | `[validMaxItemSelected]="{ value: 5, message: 'Tối đa 5 mục' }"` |
+| `[validRequired]` | `IMessageTranslate` | `undefined` | Bật validation bắt buộc chọn; truyền `{}` để dùng message mặc định | `[validRequired]="{ message: 'i18n_required' }"` |
+| `[zIndex]` | `number` | `undefined` | z-index cho popover overlay (mặc định 1000) | `[zIndex]="1050"` |
+
+## @Output()
+
+| Output | Type | Mô tả | Handler TS | Binding HTML |
+|---|---|---|---|---|
+| `(outChangStageFlagMouse)` | `IFlagMouse` | Emit khi trạng thái hover chuột vào/ra dropdown thay đổi (merge cả trigger và content) | `handlerChangStageFlagMouse(e: IFlagMouse): void { e; }` | `(outChangStageFlagMouse)="handlerChangStageFlagMouse($event)"` |
+| `(outChangeTabKeyActive)` | `string \| undefined` | Emit key của tab vừa được chọn | `handlerChangeTabKeyActive(e: string \| undefined): void { e; }` | `(outChangeTabKeyActive)="handlerChangeTabKeyActive($event)"` |
+| `(outClickButtonOther)` | `IButton` | Emit khi click vào button bổ sung trong danh sách (`listButtonsOther`) | `handlerClickButtonOther(e: IButton): void { e.stopPropagation(); }` | `(outClickButtonOther)="handlerClickButtonOther($event)"` |
+| `(outDataChange)` | `Array<unknown>` | Emit toàn bộ danh sách hiện tại mỗi khi dữ liệu list thay đổi (sau load/refresh) | `handlerDataChange(e: Array<unknown>): void { e; }` | `(outDataChange)="handlerDataChange($event)"` |
+| `(outFunctionsControl)` | `IDropdownFunctionControlEvent` | Emit object chứa các hàm điều khiển dropdown ngay sau `ngOnInit` | `handlerFunctionsControl(e: IDropdownFunctionControlEvent): void { this.ctrl = e; }` | `(outFunctionsControl)="handlerFunctionsControl($event)"` |
+| `(outSelectKey)` | `IEmitSelectKey \| undefined` | Emit khi chọn 1 item (single select: type text/radio); `undefined` khi bỏ chọn | `handlerSelectKey(e: IEmitSelectKey \| undefined): void { e?.key; }` | `(outSelectKey)="handlerSelectKey($event)"` |
+| `(outSelectMultiKey)` | `IEmitMultiKey \| undefined` | Emit khi chọn/bỏ chọn items (multi select: type checkbox/group); `undefined` khi reset | `handlerSelectMultiKey(e: IEmitMultiKey \| undefined): void { e?.keys; }` | `(outSelectMultiKey)="handlerSelectMultiKey($event)"` |
+| `(outShowList)` | `boolean` | Emit `true` khi mở dropdown, `false` khi đóng | `handlerShowList(e: boolean): void { e; }` | `(outShowList)="handlerShowList($event)"` |
+| `(outValidEvent)` | `boolean` | Emit kết quả validation mỗi khi thay đổi lựa chọn (`true` = hợp lệ) | `handlerValidEvent(e: boolean): void { e; }` | `(outValidEvent)="handlerValidEvent($event)"` |
+
+## FunctionControl Methods
+
+`IDropdownFunctionControlEvent` được emit qua `(outFunctionsControl)` ngay sau `ngOnInit`. Lưu vào biến và gọi khi cần:
+
+```typescript
+private dropdownControl: IDropdownFunctionControlEvent | undefined;
+
+handlerFunctionsControl(event: IDropdownFunctionControlEvent): void {
+  this.dropdownControl = event;
+}
+```
+
+| Method | Signature | Mô tả |
+|---|---|---|
+| `checkIsValid()` | `() => Promise<boolean>` | Chạy validation và trả về `true` nếu hợp lệ, `false` nếu có lỗi |
+| `getDisable()` | `() => Promise<boolean>` | Lấy trạng thái disable hiện tại |
+| `refreshList()` | `() => Promise<void>` | Reload lại danh sách từ API (gọi `httpRequestData` lại từ đầu) |
+| `removeList()` | `() => Promise<void>` | Đóng popover danh sách nếu đang mở |
+| `reset()` | `() => Promise<void>` | Reset về trạng thái ban đầu: xóa lựa chọn, xóa error |
+| `resetError()` | `() => Promise<void>` | Xóa error message đang hiển thị và border đỏ |
+| `setError(message)` | `(message: string) => Promise<void>` | Hiển thị error message tùy chỉnh (có thể truyền i18n key) |
+| `setItemSelectedByKey(id)` | `(id: unknown) => Promise<void>` | Chọn item theo key, tự gọi API `httpRequestDetailItemById` nếu có để lấy chi tiết |
+| `updateLabelItemSelected(label)` | `(label: string) => Promise<void>` | Cập nhật text hiển thị của item đã chọn mà không cần reload |
 
 ## Types & Interfaces
 
 ```typescript
+import {
+  IEmitSelectKey,
+  IEmitMultiKey,
+  IPopoverCustomConfig,
+  IDropdownTabsItem,
+  IValidMaxItemSelected,
+  IDropdown,
+  IDropdownFunctionControlEvent,
+} from '@libs-ui/components-dropdown';
+```
+
+```typescript
+// Dữ liệu emit khi chọn 1 item (single select)
 interface IEmitSelectKey {
-  key?: unknown;
-  item?: any;
-  isClickManual?: boolean;
-  tabKeyActive?: string;
+  key?: unknown;           // id / value của item đã chọn
+  item?: any;              // object item đầy đủ từ danh sách
+  isClickManual?: boolean; // true nếu người dùng click trực tiếp
+  tabKeyActive?: string;   // key tab đang active khi chọn (nếu có tabs)
 }
 
+// Dữ liệu emit khi chọn nhiều items (multi select)
 interface IEmitMultiKey {
-  keys?: Array<unknown>;
-  mapKeys?: Array<IEmitSelectKey>;
+  keys?: Array<unknown>;       // mảng id / value đã chọn
+  mapKeys?: Array<IEmitSelectKey>; // mảng chi tiết từng item đã chọn
   isClickManual?: boolean;
   tabKeyActive?: string;
 }
 
+// Cấu hình tùy chỉnh popover overlay
 interface IPopoverCustomConfig {
-  widthByParent?: boolean;
-  parentBorderWidth?: number;
-  maxHeight?: number;
-  maxWidth?: number;
-  direction?: TYPE_POPOVER_DIRECTION;
-  ignoreArrow?: boolean;
-  classInclude?: string;
-  disable?: boolean;
-  clickExactly?: boolean;
-  paddingLeftItem?: boolean;
-  timerDestroy?: number;
-  position?: { mode: TYPE_POPOVER_POSITION_MODE; distance: number };
-  animationConfig?: { time?: number; distance?: number };
-  width?: number;
-  classIncludeOverlayBody?: string;
+  widthByParent?: boolean;      // width bằng element cha
+  parentBorderWidth?: number;   // bù trừ border của element cha (px)
+  maxHeight?: number;           // chiều cao tối đa popup (px)
+  maxWidth?: number;            // chiều rộng tối đa popup (px)
+  direction?: TYPE_POPOVER_DIRECTION; // hướng mở: 'bottom' | 'top' | 'left' | 'right'
+  ignoreArrow?: boolean;        // ẩn mũi tên
+  classInclude?: string;        // class CSS bổ sung cho container popup
+  disable?: boolean;            // vô hiệu hóa popover
+  clickExactly?: boolean;       // chỉ mở khi click chính xác
+  paddingLeftItem?: boolean;    // thêm padding trái cho item
+  timerDestroy?: number;        // thời gian trễ trước khi destroy (ms)
+  position?: {
+    mode: TYPE_POPOVER_POSITION_MODE; // 'start' | 'center' | 'end'
+    distance: number;           // khoảng cách từ điểm neo (px)
+  };
+  animationConfig?: {
+    time?: number;              // thời gian animation (ms)
+    distance?: number;          // khoảng cách dịch chuyển animation (px)
+  };
+  width?: number;               // chiều rộng cố định (px)
+  classIncludeOverlayBody?: string; // class CSS cho overlay body
 }
 
+// Cấu hình từng tab trong dropdown có tabs
 interface IDropdownTabsItem {
-  key: string;
-  name: string;
-  httpRequestData?: IHttpRequestConfig;
+  key: string;                       // định danh duy nhất của tab
+  name: string;                      // tên hiển thị (hỗ trợ i18n key)
+  httpRequestData?: IHttpRequestConfig; // config API riêng cho tab này
 }
 
+// Validation giới hạn số item được chọn tối đa
 interface IValidMaxItemSelected extends IMessageTranslate {
-  value: number;
+  value: number; // số lượng tối đa cho phép chọn
 }
 
+// Cấu hình dropdown dùng để truyền vào service/helper
 interface IDropdown {
   listConfig: IListConfigItem;
   listBackgroundListCustom?: string;
@@ -338,6 +735,7 @@ interface IDropdown {
   disable?: boolean;
 }
 
+// Interface FunctionControl để điều khiển dropdown từ bên ngoài
 interface IDropdownFunctionControlEvent {
   checkIsValid: () => Promise<boolean>;
   resetError: () => Promise<void>;
@@ -351,62 +749,43 @@ interface IDropdownFunctionControlEvent {
 }
 ```
 
-| Type | Mô tả |
-|------|--------|
-| `IEmitSelectKey` | Dữ liệu emit khi chọn 1 item (single select) |
-| `IEmitMultiKey` | Dữ liệu emit khi chọn nhiều items (multi select) |
-| `IPopoverCustomConfig` | Cấu hình tùy chỉnh popover overlay |
-| `IDropdownTabsItem` | Cấu hình cho từng tab trong dropdown |
-| `IValidMaxItemSelected` | Cấu hình validation giới hạn số item được chọn |
-| `IDropdown` | Interface cấu hình dropdown |
-| `IDropdownFunctionControlEvent` | Interface chứa các methods để điều khiển dropdown từ component cha |
-
-## Dependencies
-
-| Package | Version | Mục đích |
-|---------|---------|----------|
-| `@libs-ui/components-avatar` | `0.2.355-14` | Hiển thị avatar trong dropdown |
-| `@libs-ui/components-buttons-button` | `0.2.355-14` | Button interface |
-| `@libs-ui/components-inputs-search` | `0.2.355-14` | Input tìm kiếm |
-| `@libs-ui/components-inputs-valid` | `0.2.355-14` | Validation input |
-| `@libs-ui/components-label` | `0.2.355-14` | Label component |
-| `@libs-ui/components-list` | `0.2.355-14` | Danh sách hiển thị |
-| `@libs-ui/components-popover` | `0.2.355-14` | Popover overlay |
-| `@libs-ui/pipes-security-trust` | `0.2.355-14` | Security trust pipe |
-| `@libs-ui/services-http-request` | `0.2.355-14` | HTTP request service |
-| `@libs-ui/utils` | `0.2.355-14` | Utilities |
-| `@ngx-translate/core` | `^15.0.0` | Đa ngôn ngữ |
-
-## Công nghệ
-
-| Technology | Version | Purpose |
-|------------|---------|---------|
-| Angular | 18+ | Framework |
-| Angular Signals | - | State management |
-| TailwindCSS | 3.x | Styling |
-| OnPush | - | Change Detection |
+## Sub-Component: libs_ui-components-dropdown-tabs
 
-## Demo
+Component tabs nội bộ, được sử dụng tự động khi truyền `[tabsConfig]` vào dropdown chính. Không cần import riêng.
 
-```bash
-npx nx serve core-ui
-```
+| Input | Type | Default | Mô tả | Ví dụ |
+|---|---|---|---|---|
+| `[tabsConfig]` | `Array<IDropdownTabsItem>` | `undefined` | Danh sách cấu hình tab | `[tabsConfig]="tabs"` |
+| `[(tabKeyActive)]` | `string` (model) | `undefined` | Two-way binding key tab đang active | `[(tabKeyActive)]="activeKey"` |
+| `[ignoreBorderBottom]` | `boolean` | `undefined` | Ẩn border bottom của tabs bar | `[ignoreBorderBottom]="true"` |
+| `[disable]` | `boolean` | `undefined` | Vô hiệu hóa toàn bộ tabs | `[disable]="true"` |
 
-Truy cập: http://localhost:4500/dropdown
+| Output | Type | Mô tả |
+|---|---|---|
+| `(outChange)` | `void` | Emit mỗi khi chọn tab mới |
 
-## Unit Tests
+## Lưu ý quan trọng
 
-```bash
-# Chạy tests
-npx nx test components-dropdown
+⚠️ **Bắt buộc `[listConfig]`**: Dropdown không hoạt động nếu thiếu `[listConfig]`. Đây là input quan trọng nhất xác định type hiển thị và nguồn dữ liệu.
 
-# Coverage
-npx nx test components-dropdown --coverage
+⚠️ **Chế độ chọn đơn vs nhiều**: Dùng `[(listKeySelected)]` + `(outSelectKey)` cho type `text`/`radio`. Dùng `[(listMultiKeySelected)]` + `(outSelectMultiKey)` cho type `checkbox`/`group`.
 
-# Watch mode
-npx nx test components-dropdown --watch
-```
+⚠️ **`convertItemSelected` là bắt buộc để hiển thị đúng label**: Hàm này cần gán giá trị vào field `labelDisplay` (hoặc field được chỉ định bởi `[fieldLabel]`) của item. Thiếu hàm này dropdown sẽ hiển thị trắng sau khi chọn.
 
-## License
+⚠️ **Truyền key có sẵn (`listKeySelected`/`listMultiKeySelected`) BẮT BUỘC kèm `[httpRequestDetailItemById]`** (lỗi phổ biến nhất): Khi bạn truyền key đã chọn từ server (vd: `[(listKeySelected)]="selectedId"`) mà dropdown CHƯA load list, component chỉ có **key** chứ không có **item** tương ứng để dựng label → trigger sẽ **hiển thị trắng**. Phải cấu hình `[httpRequestDetailItemById]` để dropdown tự gọi API lấy chi tiết item theo key. Nếu thiếu, component sẽ in `console.warn` cảnh báo. Xem mục _"10. Dropdown lazy-load chi tiết item theo key"_.
 
-MIT
+⚠️ **FunctionControl phát sinh sau ngOnInit**: `(outFunctionsControl)` emit 1 lần duy nhất trong `ngOnInit`. Lưu tham chiếu vào biến class để dùng sau.
+
+⚠️ **`listKeysDisable` không dùng kèm `configCheckboxCheckAll`**: Khi listConfig có cấu hình `configCheckboxCheckAll`, không được dùng `[listKeysDisable]` vì sẽ gây lỗi logic chọn tất cả.
+
+⚠️ **`listKeysHidden` không dùng kèm `configCheckboxCheckAll`**: Tương tự `listKeysDisable`, tránh dùng kết hợp với `configCheckboxCheckAll`.
+
+⚠️ **XSS Safety**: Khi `getValue`/`getLabelItem` trả về HTML có thể chứa dữ liệu từ người dùng, BẮT BUỘC bọc trong `escapeHtml()` từ `@libs-ui/utils`.
+
+## Demo
+
+```bash
+npx nx serve core-ui
+```
+
+Truy cập: http://localhost:4500/dropdown