@libs-ui/components-list 0.2.356-9 → 0.2.357-0

package/README.md

@@ -1,58 +1,61 @@
 # @libs-ui/components-list
 
-> Component mạnh mẽ hỗ trợ hiển thị danh sách với nhiều định dạng: Text, Radio, Checkbox, Tag và Group/Tree. Kèm sub-component hiển thị giao diện No-Data linh hoạt.
-
-**Version:** `0.2.356-3` | **Package:** `@libs-ui/components-list`
+> Component danh sách đa năng hỗ trợ 5 kiểu template (text, radio, checkbox, tag, group/tree) với tìm kiếm, lazy-loading HTTP và Angular Signals.
 
 ## Giới thiệu
 
-`LibsUiComponentsListComponent` là một standalone Angular component được thiết kế để xử lý các bài toán hiển thị danh sách phức tạp. Component này không chỉ hiển thị dữ liệu mà còn tích hợp sâu với các dịch vụ lấy dữ liệu (HTTP), tìm kiếm và quản lý trạng thái chọn item.
+`LibsUiComponentsListComponent` là một standalone Angular component được thiết kế để xử lý các bài toán hiển thị danh sách phức tạp. Component tích hợp sẵn tìm kiếm online/offline, lazy-loading qua HTTP, virtual scroll và quản lý trạng thái chọn item (single/multi). Mỗi kiểu hiển thị (text, radio, checkbox, tag, group/tree) được khởi tạo động thông qua `LibsUiDynamicComponentService`, giúp bundle size tối ưu và cấu hình linh hoạt.
 
-### Tính năng
+## Tính năng
 
-- ✅ **Đa dạng Template**: Hỗ trợ 5 loại hiển thị: `text`, `radio`, `checkbox`, `tag`, `group`.
-- ✅ **Cấu trúc Cây (Group/Tree)**: Hiển thị phân cấp không giới hạn level với logic quan hệ cha-con tinh tế.
-- ✅ **Tìm kiếm Thông minh**: Hỗ trợ cả tìm kiếm Online (server-side) và Offline (client-side).
+- ✅ **Đa dạng template**: Hỗ trợ 5 loại hiển thị: `text`, `radio`, `checkbox`, `tag`, `group/tree`.
+- ✅ **Cấu trúc cây (Group/Tree)**: Phân cấp không giới hạn với logic quan hệ cha-con tích hợp sẵn qua `buildListGroupConfig`.
+- ✅ **Tìm kiếm thông minh**: Hỗ trợ cả tìm kiếm online (server-side) và offline (client-side).
 - ✅ **Tích hợp HTTP**: Tự động load dữ liệu thông qua cấu hình `httpRequestData`.
 - ✅ **Virtual Scroll**: Tối ưu render danh sách lớn.
-- ✅ **OnPush Change Detection**: Tối ưu hiệu năng render.
-- ✅ **Standalone Component**: Dễ dàng import và sử dụng.
-- ✅ **Angular Signals**: State management hiện đại và reactive.
 - ✅ **Custom Row/Column**: Tùy biến layout từng item qua cấu hình `rows`/`cols`.
+- ✅ **FunctionControl API**: Điều khiển component từ bên ngoài (refresh, resetKeySelected, removeItems, updateData).
+- ✅ **Validation**: Hỗ trợ bắt buộc chọn item qua `validRequired`.
+- ✅ **OnPush + Standalone**: Hiệu năng cao, dễ import.
 
 ## Khi nào sử dụng
 
-- Khi cần hiển thị danh sách các tùy chọn cho người dùng chọn một hoặc nhiều.
-- Khi xây dựng các bộ lọc (filters) có cấu trúc phân cấp phức tạp.
-- Khi danh sách có kích thước lớn và cần tối ưu hiệu năng render (Virtual Scroll).
-- Khi muốn đồng bộ hóa việc tìm kiếm và hiển thị dữ liệu từ API một cách tự động.
-
-## ⚠️ Important Notes
-
-- **Config Type**: Phải luôn cung cấp `type` và signal config tương ứng (ví dụ: `configTemplateText` cho type `text`).
-- **Performance**: Virtual scroll được bật mặc định cho danh sách lớn. Tắt bằng cách set `notUseVirtualScroll: true` trong config.
-- **Signals**: Các cấu hình bên trong `config` (như `httpRequestData`) phải là `WritableSignal` để component có thể reactive.
-- **keysDisableItem + configCheckboxCheckAll**: Không dùng `keysDisableItem` kết hợp với template checkbox có `configCheckboxCheckAll`.
+- Khi cần danh sách tùy chọn đơn (single-select) hoặc đa (multi-select).
+- Khi xây dựng bộ lọc (filter) phân cấp dạng cây (tree structure).
+- Khi danh sách có kích thước lớn, cần lazy-loading hoặc tìm kiếm online từ API.
+- Khi cần hiển thị dữ liệu danh sách với layout item phức tạp (nhiều dòng, nhiều cột).
+- Khi xây dựng dropdown, menu chọn nhanh với icon và hình ảnh.
 
 ## Cài đặt
 
 ```bash
-# npm
 npm install @libs-ui/components-list
-
-# yarn
-yarn add @libs-ui/components-list
 ```
 
 ## Import
 
 ```typescript
-// Component chính
 import { LibsUiComponentsListComponent } from '@libs-ui/components-list';
-
-// Sub-component No-Data (khi cần dùng riêng)
 import { LibsUiComponentsListTemplatesNoDataComponent } from '@libs-ui/components-list';
 
+// Types & Interfaces
+import {
+  IListConfigItem,
+  IListConfigItemText,
+  IListConfigItemRadio,
+  IListConfigItemCheckbox,
+  IListConfigItemGroup,
+  IListConfigItemTag,
+  IListFunctionControlEvent,
+  IListDataEmitKey,
+  IListDataEmitMultiKey,
+  IDataUpdateToStore,
+  TYPE_TEMPLATE,
+} from '@libs-ui/components-list';
+
+// Helper function để tạo cấu hình group/tree
+import { buildListGroupConfig } from '@libs-ui/components-list';
+
 @Component({
   standalone: true,
   imports: [LibsUiComponentsListComponent],
@@ -61,234 +64,600 @@ import { LibsUiComponentsListTemplatesNoDataComponent } from '@libs-ui/component
 export class YourComponent {}
 ```
 
-## Ví dụ
+## Ví dụ sử dụng
 
-### Basic (Text – Single Select)
+### Ví dụ 1 — Text (Single Select)
 
 ```html
 <libs_ui-components-list
   [config]="configText()"
   [keySelected]="keySelected()"
-  (outSelectKey)="onSelect($event)"
-  (outFunctionsControl)="onFunctionsControl($event)"></libs_ui-components-list>
+  (outSelectKey)="handlerSelectKey($event)"
+  (outFunctionsControl)="handlerFunctionsControl($event)">
+</libs_ui-components-list>
 ```
 
 ```typescript
-configText = signal<IListConfigItem>({
-  type: 'text',
-  httpRequestData: signal<IHttpRequestConfig>({
-    objectInstance: returnListObject(myData),
-    argumentsValue: [],
-    functionName: 'list',
-  }),
-  configTemplateText: signal({
-    fieldKey: 'id',
-    getValue: (item) => item.name || item.label,
-  }),
-});
+import { signal } from '@angular/core';
+import { LibsUiComponentsListComponent, IListConfigItem, IListDataEmitKey, IListFunctionControlEvent } from '@libs-ui/components-list';
+import { IHttpRequestConfig, returnListObject } from '@libs-ui/services-http-request';
+
+// Dữ liệu mẫu
+const sampleData = [
+  { id: '1', name: 'Nguyễn Văn An', avatar: '' },
+  { id: '2', name: 'Trần Thị Bình', avatar: '' },
+  { id: '3', name: 'Lê Quốc Cường', avatar: '' },
+];
+
+export class YourComponent {
+  protected keySelected = signal<string | undefined>('1');
+  private listFunctionControl: IListFunctionControlEvent | undefined;
+
+  protected configText = signal<IListConfigItem>({
+    type: 'text',
+    httpRequestData: signal<IHttpRequestConfig>({
+      objectInstance: returnListObject(sampleData),
+      argumentsValue: [],
+      functionName: 'list',
+    }),
+    configTemplateText: signal({
+      fieldKey: 'id',
+      getValue: (item) => item.name,
+    }),
+  });
+
+  protected handlerSelectKey(event?: IListDataEmitKey) {
+    event?.event?.stopPropagation?.();
+    this.keySelected.set(event?.key as string);
+  }
+
+  protected handlerFunctionsControl(event: IListFunctionControlEvent) {
+    this.listFunctionControl = event;
+  }
+}
 ```
 
-### Checkbox (Multi-select)
+### Ví dụ 2 — Checkbox (Multi Select)
 
 ```html
 <libs_ui-components-list
   [config]="configCheckbox()"
   [multiKeySelected]="multiKeySelected()"
-  (outSelectMultiKey)="onMultiSelect($event)"></libs_ui-components-list>
+  [searchConfig]="{ placeholder: 'Tìm kiếm...' }"
+  (outSelectMultiKey)="handlerSelectMultiKey($event)"
+  (outFunctionsControl)="handlerFunctionsControl($event)">
+</libs_ui-components-list>
 ```
 
 ```typescript
-configCheckbox = signal<IListConfigItem>({
-  type: 'checkbox',
-  configTemplateCheckbox: signal({
-    fieldKey: 'id',
-    getValue: (item) => item.name,
-  }),
-});
+import { signal } from '@angular/core';
+import { LibsUiComponentsListComponent, IListConfigItem, IListDataEmitMultiKey, IListFunctionControlEvent } from '@libs-ui/components-list';
+import { IHttpRequestConfig, returnListObject } from '@libs-ui/services-http-request';
+
+const sampleData = [
+  { id: '1', name: 'Báo cáo doanh thu' },
+  { id: '2', name: 'Báo cáo chi phí' },
+  { id: '3', name: 'Báo cáo lợi nhuận' },
+];
+
+export class YourComponent {
+  protected multiKeySelected = signal<string[]>(['1', '2']);
+  private listFunctionControl: IListFunctionControlEvent | undefined;
+
+  protected configCheckbox = signal<IListConfigItem>({
+    type: 'checkbox',
+    httpRequestData: signal<IHttpRequestConfig>({
+      objectInstance: returnListObject(sampleData),
+      argumentsValue: [],
+      functionName: 'list',
+    }),
+    configTemplateCheckbox: signal({
+      fieldKey: 'id',
+      getValue: (item) => item.name,
+    }),
+  });
+
+  protected handlerSelectMultiKey(event?: IListDataEmitMultiKey) {
+    this.multiKeySelected.set(event?.keys as string[]);
+  }
+
+  protected handlerFunctionsControl(event: IListFunctionControlEvent) {
+    this.listFunctionControl = event;
+  }
+}
+```
+
+### Ví dụ 3 — Group/Tree với `buildListGroupConfig`
+
+```html
+<libs_ui-components-list
+  [config]="configGroup()"
+  [multiKeySelected]="multiKeySelected()"
+  (outSelectMultiKey)="handlerSelectMultiKey($event)">
+</libs_ui-components-list>
+```
+
+```typescript
+import { signal } from '@angular/core';
+import { LibsUiComponentsListComponent, IListConfigItem, IListDataEmitMultiKey, buildListGroupConfig } from '@libs-ui/components-list';
+import { IHttpRequestConfig, returnListObject } from '@libs-ui/services-http-request';
+
+const groupData = [
+  {
+    id: 'g1',
+    name: 'Nhóm A',
+    items: [
+      { id: 'a1', name: 'Item A1' },
+      { id: 'a2', name: 'Item A2' },
+    ],
+  },
+  {
+    id: 'g2',
+    name: 'Nhóm B',
+    items: [
+      { id: 'b1', name: 'Item B1' },
+      { id: 'b2', name: 'Item B2' },
+    ],
+  },
+];
+
+export class YourComponent {
+  protected multiKeySelected = signal<string[]>([]);
+
+  // buildListGroupConfig tạo sẵn cấu hình cho các pattern phổ biến
+  protected configGroup = signal<IListConfigItem>({
+    type: 'group',
+    httpRequestData: signal<IHttpRequestConfig>({
+      objectInstance: returnListObject(groupData),
+      argumentsValue: [],
+      functionName: 'list',
+    }),
+    configTemplateGroup: buildListGroupConfig('group_tree_checkbox_1'),
+  });
+
+  protected handlerSelectMultiKey(event?: IListDataEmitMultiKey) {
+    this.multiKeySelected.set(event?.keys as string[]);
+  }
+}
 ```
 
-### Tag + Search
+### Ví dụ 4 — Radio
+
+```html
+<libs_ui-components-list
+  [config]="configRadio()"
+  [keySelected]="keySelected()"
+  (outSelectKey)="handlerSelectKey($event)">
+</libs_ui-components-list>
+```
+
+```typescript
+import { signal } from '@angular/core';
+import { LibsUiComponentsListComponent, IListConfigItem, IListDataEmitKey } from '@libs-ui/components-list';
+import { IHttpRequestConfig, returnListObject } from '@libs-ui/services-http-request';
+
+const sampleData = [
+  { id: 'all', name: 'Tất cả' },
+  { id: 'active', name: 'Đang hoạt động' },
+  { id: 'inactive', name: 'Ngừng hoạt động' },
+];
+
+export class YourComponent {
+  protected keySelected = signal<string | undefined>('all');
+
+  protected configRadio = signal<IListConfigItem>({
+    type: 'radio',
+    httpRequestData: signal<IHttpRequestConfig>({
+      objectInstance: returnListObject(sampleData),
+      argumentsValue: [],
+      functionName: 'list',
+    }),
+    configTemplateRadio: signal({
+      fieldKey: 'id',
+      getValue: (item) => item.name,
+    }),
+  });
+
+  protected handlerSelectKey(event?: IListDataEmitKey) {
+    this.keySelected.set(event?.key as string);
+  }
+}
+```
+
+### Ví dụ 5 — Tag
 
 ```html
 <libs_ui-components-list
   [config]="configTag()"
-  [searchConfig]="{ placeholder: 'Tìm theo tên...' }"></libs_ui-components-list>
+  [searchConfig]="{ placeholder: 'Tìm theo tên...' }"
+  [multiKeySelected]="multiKeySelected()"
+  (outSelectMultiKey)="handlerSelectMultiKey($event)">
+</libs_ui-components-list>
 ```
 
 ```typescript
-configTag = signal<IListConfigItem>({
-  type: 'tag',
-  configTemplateTag: signal({ fieldKey: 'id', getValue: (item) => item.name }),
-});
+import { signal } from '@angular/core';
+import { LibsUiComponentsListComponent, IListConfigItem, IListDataEmitMultiKey } from '@libs-ui/components-list';
+import { IHttpRequestConfig, returnListObject } from '@libs-ui/services-http-request';
+
+const tagData = [
+  { id: '1', name: 'Angular' },
+  { id: '2', name: 'TypeScript' },
+  { id: '3', name: 'RxJS' },
+  { id: '4', name: 'Signals' },
+];
+
+export class YourComponent {
+  protected multiKeySelected = signal<string[]>([]);
+
+  protected configTag = signal<IListConfigItem>({
+    type: 'tag',
+    httpRequestData: signal<IHttpRequestConfig>({
+      objectInstance: returnListObject(tagData),
+      argumentsValue: [],
+      functionName: 'list',
+    }),
+    configTemplateTag: signal({
+      fieldKey: 'id',
+      getValue: (item) => item.name,
+    }),
+  });
+
+  protected handlerSelectMultiKey(event?: IListDataEmitMultiKey) {
+    this.multiKeySelected.set(event?.keys as string[]);
+  }
+}
 ```
 
-### Group / Tree
+### Ví dụ 6 — Custom Row & Column
+
+```html
+<libs_ui-components-list [config]="configCustomRow()">
+</libs_ui-components-list>
+```
 
 ```typescript
-import { buildListGroupConfig } from '@libs-ui/components-list';
+import { signal } from '@angular/core';
+import { of } from 'rxjs';
+import { LibsUiComponentsListComponent, IListConfigItem } from '@libs-ui/components-list';
+import { IHttpRequestConfig, returnListObject } from '@libs-ui/services-http-request';
+import { get } from '@libs-ui/utils';
+
+const richData = [
+  { id: '1', name: 'Nguyễn Văn An', subTitle: 'Trưởng phòng', desc: 'Kinh nghiệm 5 năm' },
+  { id: '2', name: 'Trần Thị Bình', subTitle: 'Nhân viên', desc: 'Kinh nghiệm 2 năm' },
+];
+
+export class YourComponent {
+  protected configCustomRow = signal<IListConfigItem>({
+    type: 'text',
+    httpRequestData: signal<IHttpRequestConfig>({
+      objectInstance: returnListObject(richData),
+      argumentsValue: [],
+      functionName: 'list',
+    }),
+    configTemplateText: signal({
+      fieldKey: 'id',
+      rows: signal([
+        signal({
+          classRow: 'flex flex-col mb-1',
+          cols: signal([
+            signal({ getValue: (data) => of(get(data, 'item.name') as string) }),
+            signal({ getValue: (data) => of(get(data, 'item.subTitle') as string) }),
+          ]),
+        }),
+        signal({
+          classRow: 'text-sm text-gray-500 mt-1',
+          getValue: (data) => of(get(data, 'item.desc') as string),
+        }),
+      ]),
+    }),
+  });
+}
+```
 
-configGroup = signal<IListConfigItem>({
-  type: 'group',
-  configTemplateGroup: buildListGroupConfig('group_tree_checkbox_1'),
-});
+### Ví dụ 7 — FunctionControl: refresh, resetKeySelected, removeItems
+
+```typescript
+import { signal } from '@angular/core';
+import { LibsUiComponentsListComponent, IListFunctionControlEvent } from '@libs-ui/components-list';
+
+export class YourComponent {
+  private listFunctionControl: IListFunctionControlEvent | undefined;
+
+  protected handlerFunctionsControl(event: IListFunctionControlEvent) {
+    this.listFunctionControl = event;
+  }
+
+  protected handlerRefreshList() {
+    this.listFunctionControl?.refresh();
+  }
+
+  protected handlerResetSelection() {
+    this.listFunctionControl?.resetKeySelected();
+  }
+
+  protected handlerRemoveItems(keys: string[]) {
+    this.listFunctionControl?.removeItems(keys);
+  }
+
+  protected async handlerValidate(): Promise<boolean> {
+    return this.listFunctionControl?.checkIsValid() ?? true;
+  }
+}
 ```
 
-### Custom Row & Column
+### Ví dụ 8 — Saved Views (Group flat với single-select item)
+
+```html
+<libs_ui-components-list
+  [config]="configSavedViews()"
+  [keySelected]="savedViewKeySelected()"
+  (outSelectKey)="handlerSelectedSavedView($event)">
+</libs_ui-components-list>
+```
 
 ```typescript
-configCustomRow = signal<IListConfigItem>({
-  type: 'text',
-  configTemplateText: signal({
-    fieldKey: 'id',
-    rows: signal([
-      signal({
-        classRow: 'flex flex-col',
-        cols: signal([signal({ getValue: (data) => of(`<b>${data.item.name}</b>`) }), signal({ getValue: (data) => of(data.item.subTitle) })]),
-      }),
-      signal({ getValue: (data) => of(data.item.desc) }),
-    ]),
-  }),
-});
+import { signal } from '@angular/core';
+import { LibsUiComponentsListComponent, IListConfigItem, IListDataEmitKey } from '@libs-ui/components-list';
+import { IHttpRequestConfig, returnListObject } from '@libs-ui/services-http-request';
+
+const savedViewGroups = [
+  {
+    key: 'my_views',
+    label: 'Views của tôi',
+    views: [
+      { key: 'view_high_value', label: 'Khách hàng giá trị cao' },
+      { key: 'view_new', label: 'Khách hàng mới' },
+    ],
+  },
+  {
+    key: 'shared_views',
+    label: 'Views chia sẻ',
+    views: [
+      { key: 'view_vip', label: 'VIP' },
+    ],
+  },
+];
+
+export class YourComponent {
+  protected savedViewKeySelected = signal<string[] | undefined>(['view_high_value']);
+
+  protected configSavedViews = signal<IListConfigItem>({
+    type: 'group',
+    httpRequestData: signal<IHttpRequestConfig>({
+      objectInstance: returnListObject(savedViewGroups),
+      argumentsValue: [],
+      functionName: 'list',
+    }),
+    configTemplateGroup: signal({
+      fieldKey: 'key',
+      fieldGetItems: 'views',
+      getLabelGroup: (group) => `${group.label} (${group.views.length})`,
+      getMaxLevelGroup: () => 2,
+      getLabelItem: (item) => item.label,
+      singleSelectItem: true,
+      hasIconCheckSingleSelectItem: true,
+      hasBackgroundColorWhenItemSelected: true,
+      colorBlueWhenItemSelected: true,
+      iconExpand: 'right',
+      ignoreCheckboxGroup: true,
+      ignoreCheckboxItem: true,
+      getExpandGroup: () => true,
+    }),
+  });
+
+  protected handlerSelectedSavedView(event?: IListDataEmitKey) {
+    this.savedViewKeySelected.set(event ? [event.key as string] : undefined);
+  }
+}
 ```
 
-### No-Data (Default)
+## @Input()
+
+### `libs_ui-components-list`
+
+| Input | Type | Default | Mô tả | Ví dụ |
+|---|---|---|---|---|
+| `autoSelectedFirstItemCallOutsideBefore` | `boolean` | `false` | Tự động chọn item đầu tiên nếu chưa có item nào được chọn khi component khởi tạo. | `[autoSelectedFirstItemCallOutsideBefore]="true"` |
+| `backgroundListCustom` | `string` | `'bg-[#ffffff]'` | Class màu nền tùy chỉnh cho container danh sách. | `[backgroundListCustom]="'bg-gray-50'"` |
+| `buttonsOther` | `IButton[] \| undefined` | `undefined` | Danh sách các nút bấm bổ sung hiển thị phía trên danh sách. | `[buttonsOther]="extraButtons"` |
+| `clickExactly` | `boolean` | `undefined` | Chỉ kích hoạt sự kiện chọn khi click trực tiếp vào vùng item, không kích hoạt khi click vào popover hoặc vùng ngoài. | `[clickExactly]="true"` |
+| `config` | `IListConfigItem` | **BẮT BUỘC** | Cấu hình chính cho component: loại template, nguồn dữ liệu, config hiển thị item. | `[config]="configText()"` |
+| `disable` | `boolean` | `undefined` | Vô hiệu hóa toàn bộ component, không cho phép chọn item. | `[disable]="isDisabled()"` |
+| `disableLabel` | `boolean` | `undefined` | Vô hiệu hóa phần label tiêu đề của danh sách. | `[disableLabel]="true"` |
+| `dividerClassInclude` | `string` | `undefined` | Class CSS bổ sung cho đường kẻ phân cách giữa các phần. | `[dividerClassInclude]="'border-blue-200'"` |
+| `dropdownTabKeyActive` | `string` | `undefined` | Key của tab đang active trong dropdown. Thay đổi giá trị này sẽ trigger refresh danh sách. | `[dropdownTabKeyActive]="activeTab()"` |
+| `focusInputSearch` | `boolean` | `undefined` | Tự động focus vào ô tìm kiếm sau khi dữ liệu load xong. | `[focusInputSearch]="true"` |
+| `functionGetItemsAutoAddList` | `(() => Array<any>) \| undefined` | `undefined` | Hàm trả về danh sách item được thêm tự động vào đầu danh sách (ví dụ: option "Tất cả"). | `[functionGetItemsAutoAddList]="getExtraItems"` |
+| `hasButtonUnSelectOption` | `boolean` | `undefined` | Hiển thị nút "Bỏ chọn" để xóa toàn bộ lựa chọn hiện tại. | `[hasButtonUnSelectOption]="true"` |
+| `hasDivider` | `boolean` | `true` | Hiển thị đường kẻ phân cách giữa các phần (search bar và danh sách). | `[hasDivider]="false"` |
+| `hiddenInputSearch` | `boolean` | `false` | Ẩn thanh tìm kiếm. Mặc định hiển thị. | `[hiddenInputSearch]="true"` |
+| `ignoreClassDisableDefaultWhenUseKeysDisableItem` | `boolean` | `undefined` | Bỏ class CSS disable mặc định khi dùng `keysDisableItem`, cho phép tự xử lý UI disabled từng phần trong rows. | `[ignoreClassDisableDefaultWhenUseKeysDisableItem]="true"` |
+| `isSearchOnline` | `boolean` | `undefined` | Bật chế độ tìm kiếm từ server (call API với keyword). Mặc định là tìm kiếm client-side. | `[isSearchOnline]="true"` |
+| `keySearch` | `string` | `undefined` | Giá trị keyword tìm kiếm được truyền vào từ bên ngoài. | `[keySearch]="searchKeyword()"` |
+| `keySelected` | `unknown` | `undefined` | Key của item đang được chọn (single select). Dùng cho type `text` và `radio`. | `[keySelected]="selectedId()"` |
+| `keysDisableItem` | `Array<unknown> \| undefined` | `undefined` | Danh sách các key bị vô hiệu hóa, không thể chọn. Không dùng kết hợp với `configCheckboxCheckAll`. | `[keysDisableItem]="disabledIds()"` |
+| `keysHiddenItem` | `Array<unknown> \| undefined` | `undefined` | Danh sách các key bị ẩn khỏi danh sách. Không dùng kết hợp với `configCheckboxCheckAll`. | `[keysHiddenItem]="hiddenIds()"` |
+| `labelConfig` | `ILabel` | `undefined` | Cấu hình label tiêu đề hiển thị phía trên danh sách. | `[labelConfig]="{ label: 'Chọn danh mục' }"` |
+| `loadingIconSize` | `'large' \| 'medium' \| 'small' \| 'smaller' \| undefined` | `undefined` | Kích thước icon loading khi đang tải dữ liệu. | `[loadingIconSize]="'small'"` |
+| `maxItemShow` | `number` | `undefined` | Số lượng item tối đa hiển thị trong viewport trước khi bắt đầu scroll. | `[maxItemShow]="5"` |
+| `multiKeySelected` | `Array<unknown> \| undefined` | `undefined` | Danh sách các key đang được chọn (multi select). Dùng cho type `checkbox` và `group`. | `[multiKeySelected]="selectedIds()"` |
+| `paddingLeftItem` | `boolean` | `undefined` | Thêm padding bên trái cho các item trong danh sách. | `[paddingLeftItem]="true"` |
+| `resetKeyWhenSelectAllKeyDropdown` | `boolean` | `undefined` | Reset key đã chọn khi người dùng chọn option "Tất cả" trong dropdown. | `[resetKeyWhenSelectAllKeyDropdown]="true"` |
+| `searchConfig` | `IInputSearchConfig` | `{}` | Cấu hình chi tiết cho ô tìm kiếm (placeholder, debounce, v.v.). | `[searchConfig]="{ placeholder: 'Tìm kiếm...' }"` |
+| `searchPadding` | `boolean` | `undefined` | Thêm padding cho container thanh tìm kiếm. | `[searchPadding]="true"` |
+| `showValidateBottom` | `boolean` | `undefined` | Hiển thị thông báo lỗi validation ở phía dưới danh sách thay vì phía trên. | `[showValidateBottom]="true"` |
+| `skipFocusInputWhenKeySearchStoreUndefined` | `boolean` | `undefined` | Bỏ qua auto-focus vào ô tìm kiếm khi `keySearchStore` đang là `undefined`. | `[skipFocusInputWhenKeySearchStoreUndefined]="true"` |
+| `templateRefNotSearchNoData` | `TemplateRef \| undefined` | `undefined` | Template tùy chỉnh hiển thị khi chưa có từ khóa tìm kiếm và danh sách rỗng. | `[templateRefNotSearchNoData]="tplNoData"` |
+| `templateRefSearchNoData` | `TemplateRef \| undefined` | `undefined` | Template tùy chỉnh hiển thị khi tìm kiếm không có kết quả. | `[templateRefSearchNoData]="tplNoResult"` |
+| `validRequired` | `IValidRequired \| undefined` | `undefined` | Cấu hình bắt buộc phải chọn ít nhất một item. Tích hợp với form validation. | `[validRequired]="{ message: 'Vui lòng chọn ít nhất 1 mục' }"` |
+| `zIndex` | `number` | `undefined` | Z-index CSS cho container danh sách, dùng khi cần quản lý lớp hiển thị. | `[zIndex]="100"` |
+
+## @Output()
+
+### `libs_ui-components-list`
+
+| Output | Type | Mô tả | Handler TS | Binding HTML |
+|---|---|---|---|---|
+| `(outChangeView)` | `Array<any>` | Phát ra mảng item đang hiển thị sau mỗi lần danh sách thay đổi (load xong, filter, search). | `handlerChangeView(items: any[]): void { items.stopPropagation?.(); ... }` | `(outChangeView)="handlerChangeView($event)"` |
+| `(outChangStageFlagMousePopover)` | `IFlagMouse` | Phát ra trạng thái hover chuột vào/ra khỏi popover trong danh sách. | `handlerFlagMousePopover(flag: IFlagMouse): void { flag.stopPropagation?.(); ... }` | `(outChangStageFlagMousePopover)="handlerFlagMousePopover($event)"` |
+| `(outClickButtonOther)` | `IButton` | Phát ra khi người dùng click vào một trong các nút bổ sung (`buttonsOther`). | `handlerClickButtonOther(btn: IButton): void { btn.stopPropagation?.(); ... }` | `(outClickButtonOther)="handlerClickButtonOther($event)"` |
+| `(outFieldKey)` | `string \| undefined` | Phát ra tên trường `fieldKey` đang sử dụng trong template hiện tại. | `handlerFieldKey(key: string \| undefined): void { ... }` | `(outFieldKey)="handlerFieldKey($event)"` |
+| `(outFunctionsControl)` | `IListFunctionControlEvent` | Phát ra object chứa các method điều khiển component từ bên ngoài. Nên lưu lại để gọi sau. | `handlerFunctionsControl(event: IListFunctionControlEvent): void { this.listControl = event; }` | `(outFunctionsControl)="handlerFunctionsControl($event)"` |
+| `(outKeySearch)` | `string` | Phát ra keyword mỗi khi người dùng thay đổi nội dung ô tìm kiếm. | `handlerKeySearch(keyword: string): void { this.keyword.set(keyword); }` | `(outKeySearch)="handlerKeySearch($event)"` |
+| `(outLoadItemsComplete)` | `{ items: Array<any>; paging?: IPaging }` | Phát ra sau khi HTTP request tải dữ liệu hoàn tất. | `handlerLoadComplete(event: { items: any[]; paging?: IPaging }): void { this.total.set(event.paging?.total ?? 0); }` | `(outLoadItemsComplete)="handlerLoadComplete($event)"` |
+| `(outLoading)` | `boolean` | Phát ra trạng thái loading: `true` khi đang tải, `false` khi xong. | `handlerLoading(loading: boolean): void { this.isLoading.set(loading); }` | `(outLoading)="handlerLoading($event)"` |
+| `(outSelectKey)` | `IListDataEmitKey \| undefined` | Phát ra khi người dùng chọn 1 item (single select, type `text`/`radio`). `undefined` khi bỏ chọn. | `handlerSelectKey(event?: IListDataEmitKey): void { event?.event?.stopPropagation?.(); this.selected.set(event?.key as string); }` | `(outSelectKey)="handlerSelectKey($event)"` |
+| `(outSelectMultiKey)` | `IListDataEmitMultiKey \| undefined` | Phát ra khi người dùng chọn/bỏ chọn item (multi select, type `checkbox`/`group`). | `handlerSelectMultiKey(event?: IListDataEmitMultiKey): void { this.selectedIds.set(event?.keys as string[]); }` | `(outSelectMultiKey)="handlerSelectMultiKey($event)"` |
+| `(outUnSelectMultiKey)` | `Array<unknown>` | Phát ra mảng keys bị bỏ chọn trong multi select. | `handlerUnSelectMultiKey(keys: unknown[]): void { ... }` | `(outUnSelectMultiKey)="handlerUnSelectMultiKey($event)"` |
+
+## FunctionControl (via `outFunctionsControl`)
+
+Nhận `IListFunctionControlEvent` qua `(outFunctionsControl)` để điều khiển component từ bên ngoài:
+
+| Method | Signature | Mô tả |
+|---|---|---|
+| `checkIsValid` | `() => Promise<boolean>` | Kiểm tra tính hợp lệ của lựa chọn khi có cấu hình `validRequired`. Trả về `true` nếu hợp lệ. |
+| `getRectListView` | `() => Promise<IBoundingClientRect>` | Lấy kích thước và vị trí DOM của container danh sách. |
+| `refresh` | `() => Promise<void>` | Làm mới danh sách: clone lại config và tải lại dữ liệu từ đầu. |
+| `removeItems` | `(keys: string[]) => Promise<void>` | Xóa các item khỏi store hiển thị theo danh sách keys. |
+| `resetKeySelected` | `() => Promise<void>` | Xóa toàn bộ item đang được chọn (cả single lẫn multi select). |
+| `updateData` | `(data: IDataUpdateToStore) => Promise<void>` | Cập nhật/merge dữ liệu vào store hiện tại mà không cần reload từ API. |
+
+```typescript
+// Sử dụng FunctionControl
+export class YourComponent {
+  private listControl: IListFunctionControlEvent | undefined;
+
+  protected handlerFunctionsControl(event: IListFunctionControlEvent) {
+    this.listControl = event;
+  }
+
+  protected handlerRefresh() {
+    this.listControl?.refresh();
+  }
+
+  protected async handlerSubmit(): Promise<void> {
+    const isValid = await this.listControl?.checkIsValid();
+    if (!isValid) {
+      return;
+    }
+    // proceed...
+  }
+}
+```
+
+## Sub-component: `libs_ui-components-list-templates-no_data`
+
+Component hiển thị trạng thái no-data, có thể dùng độc lập hoặc truyền qua `[templateRefSearchNoData]` / `[templateRefNotSearchNoData]`.
 
 ```html
+<!-- No data cơ bản -->
 <libs_ui-components-list-templates-no_data
-  [config]="configEmpty()"
+  [config]="configText()"
   [keySearch]="''"
   [loading]="false"
-  [enableNoData]="true"></libs_ui-components-list-templates-no_data>
-```
-
-### No-Data (Custom trước khi search)
+  [enableNoData]="true">
+</libs_ui-components-list-templates-no_data>
 
-```html
-<ng-template #tplNoData>
+<!-- Custom template khi chưa search -->
+<ng-template #tplNotSearch>
   <div class="flex flex-col items-center p-4">
     <span>Vui lòng nhập thông tin để tìm kiếm.</span>
   </div>
 </ng-template>
 
 <libs_ui-components-list-templates-no_data
-  [config]="configEmpty()"
+  [config]="configText()"
   [keySearch]="''"
   [loading]="false"
   [enableNoData]="true"
-  [templateRefNotSearchNoData]="tplNoData"></libs_ui-components-list-templates-no_data>
-```
+  [templateRefNotSearchNoData]="tplNotSearch">
+</libs_ui-components-list-templates-no_data>
 
-### No-Result (Custom sau khi search)
-
-```html
-<ng-template
-  #tplNoResult
-  let-keySearch="keySearch">
-  <div>
-    Không có kết quả cho:
-    <b>{{ keySearch }}</b>
+<!-- Custom template khi search không có kết quả -->
+<ng-template #tplNoResult let-keySearch="keySearch">
+  <div class="p-4 text-center text-gray-500">
+    Không tìm thấy kết quả cho: <b>{{ keySearch }}</b>
   </div>
 </ng-template>
 
 <libs_ui-components-list-templates-no_data
-  [config]="configEmpty()"
-  [keySearch]="searchKeyword"
+  [config]="configText()"
+  [keySearch]="'từ khóa tìm kiếm'"
   [loading]="false"
   [enableNoData]="true"
-  [templateRefSearchNoData]="tplNoResult"></libs_ui-components-list-templates-no_data>
+  [templateRefSearchNoData]="tplNoResult">
+</libs_ui-components-list-templates-no_data>
 ```
 
-## API
-
-### libs_ui-components-list
-
-#### Inputs
-
-| Property                                          | Type                             | Default        | Description                                                                |
-| ------------------------------------------------- | -------------------------------- | -------------- | -------------------------------------------------------------------------- |
-| `autoSelectedFirstItemCallOutsideBefore`          | `boolean`                        | `false`        | Tự động chọn item đầu tiên nếu chưa có item nào được chọn.                 |
-| `backgroundListCustom`                            | `string`                         | `bg-[#ffffff]` | Màu nền tùy chỉnh cho danh sách.                                           |
-| `buttonsOther`                                    | `IButton[]`                      | `undefined`    | Danh sách các nút bấm khác hiển thị cuối danh sách.                        |
-| `clickExactly`                                    | `boolean`                        | `undefined`    | Chỉ kích hoạt chọn khi click chính xác vào item.                           |
-| `config`                                          | `IListConfigItem`                | **REQUIRED**   | Cấu hình chính (loại template, logic lấy dữ liệu...).                      |
-| `disable`                                         | `boolean`                        | `false`        | Vô hiệu hóa toàn bộ component.                                             |
-| `disableLabel`                                    | `boolean`                        | `false`        | Vô hiệu hóa nhãn (label).                                                  |
-| `dividerClassInclude`                             | `string`                         | `undefined`    | Class CSS bổ sung cho đường kẻ phân cách.                                  |
-| `dropdownTabKeyActive`                            | `string`                         | `undefined`    | Key của tab đang active trong dropdown.                                    |
-| `focusInputSearch`                                | `boolean`                        | `undefined`    | Tự động focus vào ô tìm kiếm khi dữ liệu load xong.                        |
-| `functionGetItemsAutoAddList`                     | `() => Array<any>`               | `undefined`    | Hàm lấy danh sách item tự động thêm vào list.                              |
-| `hasButtonUnSelectOption`                         | `boolean`                        | `undefined`    | Hiển thị nút bỏ chọn tất cả.                                               |
-| `hasDivider`                                      | `boolean`                        | `true`         | Hiển thị gạch phân cách giữa các phần.                                     |
-| `hiddenInputSearch`                               | `boolean`                        | `false`        | Ẩn/hiện thanh tìm kiếm.                                                    |
-| `ignoreClassDisableDefaultWhenUseKeysDisableItem` | `boolean`                        | `undefined`    | Bỏ class disable mặc định khi dùng `keysDisableItem`.                      |
-| `isSearchOnline`                                  | `boolean`                        | `false`        | Bật tìm kiếm từ Server (call API).                                         |
-| `keySearch`                                       | `string`                         | `undefined`    | Giá trị tìm kiếm khởi tạo.                                                 |
-| `keySelected`                                     | `any`                            | `undefined`    | Key đang chọn (single select).                                             |
-| `keysDisableItem`                                 | `Array<any>`                     | `undefined`    | Danh sách các keys bị vô hiệu hóa.                                         |
-| `keysHiddenItem`                                  | `Array<any>`                     | `undefined`    | Danh sách các keys bị ẩn đi.                                               |
-| `labelConfig`                                     | `ILabel`                         | `undefined`    | Cấu hình label tiêu đề cho danh sách.                                      |
-| `loadingIconSize`                                 | `'large' \| 'medium' \| 'small'` | `undefined`    | Kích thước icon loading.                                                   |
-| `maxItemShow`                                     | `number`                         | `undefined`    | Số lượng item tối đa hiển thị trước khi scroll.                            |
-| `multiKeySelected`                                | `Array<any>`                     | `[]`           | Danh sách keys đang chọn (multi select).                                   |
-| `paddingLeftItem`                                 | `boolean`                        | `undefined`    | Thêm padding bên trái cho item.                                            |
-| `resetKeyWhenSelectAllKeyDropdown`                | `boolean`                        | `undefined`    | Reset key khi chọn tất cả trong dropdown.                                  |
-| `searchConfig`                                    | `IInputSearchConfig`             | `{}`           | Cấu hình chi tiết cho ô tìm kiếm.                                          |
-| `searchPadding`                                   | `boolean`                        | `undefined`    | Thêm padding cho thanh tìm kiếm.                                           |
-| `showValidateBottom`                              | `boolean`                        | `undefined`    | Hiển thị thông báo validate ở phía dưới.                                   |
-| `skipFocusInputWhenKeySearchStoreUndefined`       | `boolean`                        | `undefined`    | Bỏ qua focus input nếu `keySearchStore` là undefined.                      |
-| `templateRefSearchNoData`                         | `TemplateRef`                    | `undefined`    | Template hiển thị khi tìm kiếm không có kết quả.                           |
-| `templateRefNotSearchNoData`                      | `TemplateRef`                    | `undefined`    | Template hiển thị khi không trong trạng thái tìm kiếm và không có dữ liệu. |
-| `validRequired`                                   | `IValidRequired`                 | `undefined`    | Cấu hình bắt buộc phải chọn item.                                          |
-| `zIndex`                                          | `number`                         | `undefined`    | Z-index cho danh sách.                                                     |
-
-#### Outputs
-
-| Property                          | Type                                      | Description                                              |
-| --------------------------------- | ----------------------------------------- | -------------------------------------------------------- |
-| `(outChangeView)`                 | `Array<any>`                              | Phát ra khi danh sách hiển thị thay đổi (ví dụ sau lọc). |
-| `(outChangStageFlagMousePopover)` | `IFlagMouse`                              | Phát ra trạng thái hover chuột cho popover.              |
-| `(outClickButtonOther)`           | `IButton`                                 | Phát ra khi click vào các nút bấm bổ sung.               |
-| `(outFieldKey)`                   | `string`                                  | Phát ra key của trường dữ liệu được chọn.                |
-| `(outFunctionsControl)`           | `IListFunctionControlEvent`               | Cung cấp các method điều khiển từ bên ngoài.             |
-| `(outKeySearch)`                  | `string`                                  | Phát ra khi keyword tìm kiếm thay đổi.                   |
-| `(outLoadItemsComplete)`          | `{ items: Array<any>, paging?: IPaging }` | Phát ra khi việc tải dữ liệu hoàn tất.                   |
-| `(outLoading)`                    | `boolean`                                 | Trạng thái đang tải dữ liệu.                             |
-| `(outSelectKey)`                  | `IListDataEmitKey`                        | Phát ra khi chọn 1 item (Single Select).                 |
-| `(outSelectMultiKey)`             | `IListDataEmitMultiKey`                   | Phát ra khi chọn nhiều item (Multi Select).              |
-| `(outUnSelectMultiKey)`           | `Array<unknown>`                          | Phát ra danh sách các keys bị bỏ chọn.                   |
-
-#### Methods (via `outFunctionsControl`)
-
-| Method               | Parameters                 | Description                                                 |
-| -------------------- | -------------------------- | ----------------------------------------------------------- |
-| `checkIsValid()`     | `-`                        | Kiểm tra tính hợp lệ của lựa chọn (nếu có `validRequired`). |
-| `getRectListView()`  | `-`                        | Lấy kích thước và vị trí của list view container.           |
-| `refresh()`          | `-`                        | Làm mới danh sách và tải lại dữ liệu từ đầu.                |
-| `removeItems()`      | `keys: Array<any>`         | Xóa các item cụ thể khỏi danh sách theo keys.               |
-| `resetKeySelected()` | `-`                        | Xóa sạch toàn bộ các item đang được chọn.                   |
-| `updateData()`       | `data: IDataUpdateToStore` | Cập nhật dữ liệu cụ thể vào store của list.                 |
-
-### libs_ui-components-list-templates-no_data
-
-Sub-component hiển thị giao diện trạng thái No-Data, có thể dùng độc lập hoặc tích hợp qua `[templateRefSearchNoData]` / `[templateRefNotSearchNoData]`.
-
-#### Inputs
-
-| Property                     | Type              | Default      | Description                                                                    |
-| ---------------------------- | ----------------- | ------------ | ------------------------------------------------------------------------------ |
-| `config`                     | `IListConfigItem` | **REQUIRED** | Cấu hình list (dùng để lấy `textNoData`).                                      |
-| `keySearch`                  | `string`          | `''`         | Keyword đang search. Nếu rỗng → hiển thị no-data; nếu có → hiển thị no-result. |
-| `loading`                    | `boolean`         | `false`      | Đang tải dữ liệu — khi `true` sẽ không hiển thị no-data.                       |
-| `enableNoData`               | `boolean`         | `false`      | Bật/tắt hiển thị trạng thái no-data.                                           |
-| `templateRefNotSearchNoData` | `TemplateRef`     | `undefined`  | Template tùy chỉnh khi chưa tìm kiếm (keySearch rỗng).                         |
-| `templateRefSearchNoData`    | `TemplateRef`     | `undefined`  | Template tùy chỉnh khi tìm kiếm không có kết quả.                              |
+### @Input() của `libs_ui-components-list-templates-no_data`
 
-## Types & Interfaces
+| Input | Type | Default | Mô tả | Ví dụ |
+|---|---|---|---|---|
+| `config` | `IListConfigItem \| undefined` | `undefined` | Cấu hình list để lấy text no-data tùy chỉnh (`textNoData`). | `[config]="configText()"` |
+| `enableNoData` | `boolean` | **BẮT BUỘC** | Bật/tắt hiển thị trạng thái no-data. Phải là `true` để component hiển thị. | `[enableNoData]="true"` |
+| `keySearch` | `string` | **BẮT BUỘC** | Keyword tìm kiếm hiện tại. Rỗng → hiển thị no-data; có giá trị → hiển thị no-result. | `[keySearch]="keyword()"` |
+| `loading` | `boolean` | **BẮT BUỘC** | Trạng thái đang tải. Khi `true` không hiển thị no-data. | `[loading]="isLoading()"` |
+| `templateRefNotSearchNoData` | `TemplateRef \| undefined` | `undefined` | Template tùy chỉnh khi chưa có từ khóa tìm kiếm (keySearch rỗng). | `[templateRefNotSearchNoData]="tplNotSearch"` |
+| `templateRefSearchNoData` | `TemplateRef \| undefined` | `undefined` | Template tùy chỉnh khi tìm kiếm không có kết quả. Context: `{ keySearch: string }`. | `[templateRefSearchNoData]="tplNoResult"` |
+
+## Helper: `buildListGroupConfig`
+
+Hàm tiện ích tạo sẵn cấu hình `IListConfigItemGroup` theo các pattern phổ biến:
 
 ```typescript
-export type TYPE_TEMPLATE = 'checkbox' | 'group' | 'radio' | 'text' | 'tag';
+import { buildListGroupConfig } from '@libs-ui/components-list';
+
+// Tham số 1: template name
+// Tham số 2: overrides (tùy chọn) — ghi đè fieldKey, fieldGetItems, getLabelGroup, getLabelItem, getMaxLevelGroup
+const groupConfig = buildListGroupConfig('group_tree_checkbox_1', {
+  fieldKey: 'code',
+  fieldGetItems: 'children',
+  getLabelGroup: (g) => g.categoryName,
+  getLabelItem: (item) => item.productName,
+});
+```
+
+| Template | Mô tả |
+|---|---|
+| `group_tree_checkbox_1` | Tree nhiều cấp, checkbox, logic Bank: chọn con → chọn cha; bỏ cha → bỏ hết con. |
+| `group_tree_checkbox_2` | Tree nhiều cấp, checkbox, logic Retail: chọn cha → chọn hết con; bỏ cha không bỏ con. |
+| `group_tree_radio_1` | Tree nhiều cấp, radio, single-select theo logic child triggers parent. |
+| `group_tree_radio_2` | Tree nhiều cấp, radio, single-select (biến thể emit all item checked). |
+| `group_tree_text_1` | Tree nhiều cấp, text, single-select theo logic Bank. |
+| `group_tree_text_2` | Tree nhiều cấp, text, single-select theo logic Retail. |
+| `group_label_checkbox_1` | Group dạng label phân nhóm, item checkbox multi-select. |
+| `group_label_text_1` | Group dạng label phân nhóm, item text single-select với icon check. |
 
-export interface IListConfigItem {
+## Types & Interfaces
+
+```typescript
+import {
+  TYPE_TEMPLATE,
+  IListConfigItem,
+  IListConfigItemText,
+  IListConfigItemRadio,
+  IListConfigItemCheckbox,
+  IListConfigItemGroup,
+  IListConfigItemTag,
+  IListConfigItemTextRow,
+  IListConfigItemTextCol,
+  IListDataEmitKey,
+  IListDataEmitMultiKey,
+  IListFunctionControlEvent,
+  IDataUpdateToStore,
+  IDataFunctionCallInConfig,
+  IConfigDescriptionGroup,
+  CONFIG_LIST_GROUP_TYPE,
+} from '@libs-ui/components-list';
+
+// Kiểu template
+type TYPE_TEMPLATE = 'checkbox' | 'group' | 'radio' | 'text' | 'tag';
+
+// Cấu hình chính
+interface IListConfigItem {
   type: TYPE_TEMPLATE;
   httpRequestData?: WritableSignal<IHttpRequestConfig>;
   configTemplateText?: WritableSignal<IListConfigItemText>;
@@ -296,53 +665,73 @@ export interface IListConfigItem {
   configTemplateCheckbox?: WritableSignal<IListConfigItemCheckbox>;
   configTemplateGroup?: WritableSignal<IListConfigItemGroup>;
   configTemplateTag?: WritableSignal<IListConfigItemTag>;
-  textNoData?: string;
-  autoSelectFirstItem?: boolean;
-  sort?: (items: Array<any>) => void;
-  // ...
+  textNoData?: string;               // Text hiển thị khi không có dữ liệu
+  textNoDataClassInclude?: string;   // Class CSS cho text no-data
+  textSearchNoData?: string;         // Text khi tìm kiếm không có kết quả
+  autoSelectFirstItem?: boolean;     // Tự động chọn item đầu tiên khi có dữ liệu
+  sort?: (items: Array<any>) => void; // Hàm sort tùy chỉnh
+  hasIconNoData?: boolean;
+  ignoreShowDataWhenNotSearch?: boolean; // Ẩn danh sách khi chưa search
+  highlightTextSearchInResult?: boolean; // Highlight keyword trong kết quả
+  heightItem?: number;
+  minHeightItem?: number;
 }
 
-export interface IListDataEmitKey {
-  key: unknown;
-  item: any;
-  isClickManual: boolean;
+// Event khi chọn single item
+interface IListDataEmitKey {
+  key: unknown;         // Key của item được chọn
+  item: any;            // Toàn bộ object item
+  isClickManual: boolean; // true nếu do user click, false nếu programmatic
 }
 
-export interface IListDataEmitMultiKey {
-  keys: Array<unknown>;
-  mapKeys: Array<IListDataEmitKey>;
+// Event khi chọn nhiều item
+interface IListDataEmitMultiKey {
+  keys: Array<unknown>;          // Mảng keys được chọn
+  mapKeys: Array<IListDataEmitKey>; // Chi tiết từng item được chọn
   isClickManual: boolean;
 }
 
-export interface IListFunctionControlEvent {
+// FunctionControl API
+interface IListFunctionControlEvent {
   checkIsValid: () => Promise<boolean>;
   refresh: () => Promise<void>;
   resetKeySelected: () => Promise<void>;
   getRectListView: () => Promise<IBoundingClientRect>;
   removeItems: (keys: Array<string>) => Promise<void>;
   updateData: (data: IDataUpdateToStore) => Promise<void>;
+  setMessageError?: (message: string) => Promise<void>;
 }
 
-export interface IDataUpdateToStore {
+// Dùng cho updateData
+interface IDataUpdateToStore {
   newData: WritableSignal<Array<WritableSignal<any>>>;
-  functionCustomAddDataToStore: (newData: WritableSignal<Array<WritableSignal<any>>>, store: WritableSignal<Array<WritableSignal<any>>>) => void;
+  functionCustomAddDataToStore: (
+    newData: WritableSignal<Array<WritableSignal<any>>>,
+    store: WritableSignal<Array<WritableSignal<any>>>
+  ) => void;
 }
 ```
 
-## Demo
+## Lưu ý quan trọng
+
+⚠️ **Config bắt buộc**: Phải luôn cung cấp `type` và signal config tương ứng. Ví dụ: type `text` cần có `configTemplateText: signal({...})`, type `group` cần có `configTemplateGroup: signal({...})` hoặc dùng `buildListGroupConfig(...)`.
+
+⚠️ **WritableSignal cho config con**: Tất cả các config con (`configTemplateText`, `configTemplateCheckbox`, `httpRequestData`, v.v.) phải là `WritableSignal` để component có thể reactive và refresh đúng cách khi gọi `FunctionControl.refresh()`.
+
+⚠️ **keysDisableItem không tương thích với configCheckboxCheckAll**: Không dùng `[keysDisableItem]` kết hợp với template checkbox có cấu hình `configCheckboxCheckAll` vì sẽ gây hành vi không xác định.
 
-- **Local**: [http://localhost:4500/components/list](http://localhost:4500/components/list)
+⚠️ **keysHiddenItem không tương thích với configCheckboxCheckAll**: Tương tự như trên, không dùng `[keysHiddenItem]` kết hợp với `configCheckboxCheckAll`.
 
-## Công nghệ
+⚠️ **Virtual Scroll mặc định**: Virtual scroll được bật mặc định cho danh sách lớn. Nếu cần tắt (ví dụ: dùng trong config badge của table), set `notUseVirtualScroll: true` trong `configTemplateText`.
 
-| Technology        | Purpose                       |
-| ----------------- | ----------------------------- |
-| Angular 18+       | Framework chính               |
-| Angular Signals   | Quản lý state reactive        |
-| TailwindCSS       | Styling hệ thống              |
-| Dynamic Component | Khởi tạo template linh hoạt   |
-| Virtual Scroll    | Render danh sách lớn hiệu quả |
+⚠️ **outFunctionsControl**: Luôn lưu lại `IListFunctionControlEvent` khi nhận từ `(outFunctionsControl)` để dùng sau. Chỉ gọi các method sau khi component đã mount (ngOnInit xong).
 
-## License
+⚠️ **dropdownTabKeyActive và refresh**: Thay đổi giá trị `dropdownTabKeyActive` sẽ tự động trigger `refresh()` bên trong component. Sử dụng cơ chế này khi cần reload danh sách khi đổi tab trong dropdown.
+
+## Demo
+
+```bash
+npx nx serve core-ui
+```
 
-MIT
+Truy cập: http://localhost:4500/components/list