@libs-ui/components-datetime-dropdown 0.2.356-8 → 0.2.357-0

package/README.md

@@ -1,26 +1,38 @@
-# Datetime Dropdown
+# @libs-ui/components-datetime-dropdown
 
-> Component chọn ngày/tháng/năm/quý dạng dropdown, hỗ trợ single và multi (from-to) selection với validation tự động.
+> Component dropdown chọn ngày tháng theo từng phần (năm, tháng, quý, ngày) với hỗ trợ single/multi mode, validation tự động và responsive layout.
 
-## Version
+## Giới thiệu
 
-`0.2.355-14`
+`LibsUiComponentsDatetimeDropdownComponent` cung cấp giao diện chọn ngày tháng dạng dropdown riêng biệt cho từng đơn vị thời gian (năm, tháng, quý, ngày). Component hỗ trợ 6 định dạng hiển thị khác nhau qua `typeFormat`, chế độ chọn đơn (`single`) và chọn khoảng (`multi` từ/đến) với validation so sánh tự động giữa hai đầu. Layout tự động responsive — tự chuyển sang dạng dọc khi không đủ không gian ngang.
+
+## Tính năng
+
+- 6 định dạng: `year`, `month`, `quarter`, `year-month`, `month-day`, `year-quarter`
+- Chế độ single (chọn một thời điểm) và multi (chọn khoảng from-to)
+- Validation so sánh tự động: from phải nhỏ hơn to (có thể cấu hình)
+- Validation required với message tùy chỉnh
+- Responsive layout — tự động stack dọc khi không đủ không gian
+- Điều khiển từ bên ngoài qua `FunctionsControl` (checkIsValid, resetError, resetTime)
+- Hỗ trợ disable từng key (năm/tháng/quý/ngày) cho from và to riêng biệt
+- Ẩn các giá trị cụ thể trong dropdown (`hiddenDate`)
+- Tích hợp `ILabel` từ `@libs-ui/components-label`
 
 ## Khi nào sử dụng
 
-- Cần chọn tháng/năm/quý từ dropdown thay vì calendar picker
-- Cần chọn khoảng thời gian (from-to) với validation tự động
-- Cần tùy chỉnh format hiển thị (`year`, `month`, `quarter`, `year-month`, `month-day`, `year-quarter`)
-- Cần responsive layout tự động cho form nhỏ
+- Khi cần chọn ngày tháng theo từng phần riêng biệt thay vì dùng calendar picker
+- Khi cần chọn khoảng thời gian from-to với validation so sánh tự động
+- Khi cần format hiển thị linh hoạt (`year-month`, `month-day`, `year-quarter`, ...)
+- Khi cần điều khiển validate và reset từ component cha (submit form, reset button)
+- Khi cần responsive layout tự động co giãn theo container
 
-## Important Notes
+## Cài đặt
 
-- `selectedDateTime` sử dụng `WritableSignal` — cần tạo signal trước khi truyền vào
-- `typeFormat` quyết định số lượng và loại dropdown hiển thị
-- `isMultiple=true` sẽ hiển thị 2 nhóm dropdown (From/To) với validation so sánh
-- Component tự động responsive khi không đủ không gian
+```bash
+npm install @libs-ui/components-datetime-dropdown
+```
 
-## Cài đặt & Import
+## Import
 
 ```typescript
 import {
@@ -28,194 +40,373 @@ import {
   IEmitSingleDateDropdown,
   IEmitMultiDateDropdown,
   IDateDropdownFunctionControlEvent,
-  TYPE_DATE_DROPDOWN_FORMAT,
   IFromAndToDateLabel,
   IValidDateDropdown,
+  IDateDropdownDisableKeys,
+  IDateDropdownDisable,
+  IHiddenDate,
+  TYPE_DATE_DROPDOWN_FORMAT,
+  TYPE_DATE_FORMAT,
 } from '@libs-ui/components-datetime-dropdown';
 ```
 
 ## Ví dụ sử dụng
 
-### 1. Basic Usage (month-day single)
-
-```html
-<libs_ui-components-datetime-dropdown
-  [typeFormat]="'month-day'"
-  (outChooseSingleDate)="onSingleDateSelected($event)"
-></libs_ui-components-datetime-dropdown>
-```
+### 1. Single mode — chọn tháng và ngày (mặc định)
 
 ```typescript
-import { signal } from '@angular/core';
-import { IEmitSingleDateDropdown } from '@libs-ui/components-datetime-dropdown';
+// my-form.component.ts
+import { Component } from '@angular/core';
+import {
+  LibsUiComponentsDatetimeDropdownComponent,
+  IEmitSingleDateDropdown,
+  IDateDropdownFunctionControlEvent,
+} from '@libs-ui/components-datetime-dropdown';
+
+@Component({
+  selector: 'app-my-form',
+  standalone: true,
+  imports: [LibsUiComponentsDatetimeDropdownComponent],
+  templateUrl: './my-form.component.html',
+})
+export class MyFormComponent {
+  private dropdownControl?: IDateDropdownFunctionControlEvent;
+
+  handlerFunctionsControl(event: IDateDropdownFunctionControlEvent): void {
+    event.stopPropagation();
+    this.dropdownControl = event;
+  }
 
-onSingleDateSelected(event: IEmitSingleDateDropdown) {
-  console.log('Month:', event.month, 'Day:', event.day);
+  handlerSingleDateSelected(event: IEmitSingleDateDropdown): void {
+    event.stopPropagation();
+    console.log('Tháng:', event.month, 'Ngày:', event.day);
+  }
 }
 ```
 
-### 2. Different Formats
+```html
+<!-- my-form.component.html -->
+<libs_ui-components-datetime-dropdown
+  [typeFormat]="'month-day'"
+  (outChooseSingleDate)="handlerSingleDateSelected($event)"
+  (outFunctionsControl)="handlerFunctionsControl($event)"
+/>
+```
+
+### 2. Các định dạng khác nhau
 
 ```html
-<!-- Chỉ chọn năm -->
+<!-- Chỉ năm — đảo ngược, giới hạn từ 2020 đến 2030 -->
 <libs_ui-components-datetime-dropdown
   [typeFormat]="'year'"
   [reverseYear]="true"
   [minYear]="2020"
   [maxYear]="2030"
-  (outChooseSingleDate)="onYearSelected($event)"
-></libs_ui-components-datetime-dropdown>
-
-<!-- Chỉ chọn tháng -->
-<libs_ui-components-datetime-dropdown
-  [typeFormat]="'month'"
-  (outChooseSingleDate)="onMonthSelected($event)"
-></libs_ui-components-datetime-dropdown>
+  (outChooseSingleDate)="handlerYearSelected($event)"
+/>
 
-<!-- Chọn năm-tháng -->
+<!-- Năm - tháng -->
 <libs_ui-components-datetime-dropdown
   [typeFormat]="'year-month'"
-  (outChooseSingleDate)="onYearMonthSelected($event)"
-></libs_ui-components-datetime-dropdown>
+  (outChooseSingleDate)="handlerYearMonthSelected($event)"
+/>
 
-<!-- Chọn năm-quý -->
+<!-- Năm - quý -->
 <libs_ui-components-datetime-dropdown
   [typeFormat]="'year-quarter'"
-  (outChooseSingleDate)="onYearQuarterSelected($event)"
-></libs_ui-components-datetime-dropdown>
+  (outChooseSingleDate)="handlerYearQuarterSelected($event)"
+/>
+
+<!-- Chỉ quý -->
+<libs_ui-components-datetime-dropdown
+  [typeFormat]="'quarter'"
+  (outChooseSingleDate)="handlerQuarterSelected($event)"
+/>
 ```
 
-### 3. Multi Date Range (from-to)
+```typescript
+handlerYearSelected(event: IEmitSingleDateDropdown): void {
+  event.stopPropagation();
+  console.log('Năm:', event.year);
+}
+
+handlerYearMonthSelected(event: IEmitSingleDateDropdown): void {
+  event.stopPropagation();
+  console.log('Năm:', event.year, 'Tháng:', event.month);
+}
+
+handlerYearQuarterSelected(event: IEmitSingleDateDropdown): void {
+  event.stopPropagation();
+  console.log('Năm:', event.year, 'Quý:', event.quarter);
+}
+
+handlerQuarterSelected(event: IEmitSingleDateDropdown): void {
+  event.stopPropagation();
+  console.log('Quý:', event.quarter);
+}
+```
+
+### 3. Multi mode — chọn khoảng thời gian from-to
+
+```typescript
+// date-range-filter.component.ts
+import { Component, signal } from '@angular/core';
+import {
+  LibsUiComponentsDatetimeDropdownComponent,
+  IEmitMultiDateDropdown,
+  IEmitSingleDateDropdown,
+  IDateDropdownFunctionControlEvent,
+} from '@libs-ui/components-datetime-dropdown';
+
+@Component({
+  selector: 'app-date-range-filter',
+  standalone: true,
+  imports: [LibsUiComponentsDatetimeDropdownComponent],
+  templateUrl: './date-range-filter.component.html',
+})
+export class DateRangeFilterComponent {
+  private dropdownControl?: IDateDropdownFunctionControlEvent;
+
+  // Giá trị khởi tạo ban đầu (từ tháng 1 đến tháng 6 năm 2024)
+  readonly selectedRange: IEmitMultiDateDropdown = {
+    from: signal<IEmitSingleDateDropdown>({ year: 2024, month: 1 }),
+    to: signal<IEmitSingleDateDropdown>({ year: 2024, month: 6 }),
+  };
+
+  handlerFunctionsControl(event: IDateDropdownFunctionControlEvent): void {
+    event.stopPropagation();
+    this.dropdownControl = event;
+  }
+
+  handlerMultiDateSelected(event: IEmitMultiDateDropdown): void {
+    event.stopPropagation();
+    console.log('Từ:', event.from());
+    console.log('Đến:', event.to());
+  }
+
+  async handlerSubmit(): Promise<void> {
+    const isValid = await this.dropdownControl?.checkIsValid();
+    if (!isValid) {
+      return;
+    }
+    // Tiến hành submit
+  }
+
+  async handlerReset(): Promise<void> {
+    await this.dropdownControl?.resetTime?.();
+    await this.dropdownControl?.resetError?.();
+  }
+}
+```
 
 ```html
+<!-- date-range-filter.component.html -->
 <libs_ui-components-datetime-dropdown
   [typeFormat]="'year-month'"
   [isMultiple]="true"
-  [fromAndToDateLabel]="{ from: 'i18n_label_from', to: 'i18n_to' }"
   [selectedDateTime]="selectedRange"
-  (outChooseMultiDate)="onMultiDateSelected($event)"
-  (outFunctionsControl)="onFunctionsControl($event)"
-></libs_ui-components-datetime-dropdown>
+  [fromAndToDateLabel]="{ from: 'i18n_label_from', to: 'i18n_to' }"
+  [validRequired]="{ message: 'i18n_required', messageValidCompareTime: 'i18n_invalid_end_date_selected' }"
+  (outChooseMultiDate)="handlerMultiDateSelected($event)"
+  (outFunctionsControl)="handlerFunctionsControl($event)"
+/>
+
+<button (click)="handlerSubmit()">Tìm kiếm</button>
+<button (click)="handlerReset()">Xóa bộ lọc</button>
 ```
 
+### 4. Disable từng key (năm/tháng/quý/ngày) riêng biệt
+
 ```typescript
-import { signal, WritableSignal } from '@angular/core';
+// filter.component.ts
+import { Component, signal } from '@angular/core';
 import {
+  LibsUiComponentsDatetimeDropdownComponent,
   IEmitMultiDateDropdown,
-  IEmitSingleDateDropdown,
-  IDateDropdownFunctionControlEvent,
+  IDateDropdownDisableKeys,
 } from '@libs-ui/components-datetime-dropdown';
 
-selectedRange: IEmitMultiDateDropdown = {
-  from: signal<IEmitSingleDateDropdown>({ year: 2024, month: 1 }),
-  to: signal<IEmitSingleDateDropdown>({ year: 2024, month: 12 }),
-};
+@Component({
+  selector: 'app-filter',
+  standalone: true,
+  imports: [LibsUiComponentsDatetimeDropdownComponent],
+  templateUrl: './filter.component.html',
+})
+export class FilterComponent {
+  // Disable quý 1 và quý 4 cho phía "from"
+  readonly disabledKeys: IDateDropdownDisableKeys = {
+    from: signal({
+      quarter: signal([1, 4]),
+    }),
+    to: signal({
+      quarter: signal([]),
+    }),
+  };
+
+  handlerMultiDateSelected(event: IEmitMultiDateDropdown): void {
+    event.stopPropagation();
+    console.log('Khoảng:', event.from(), event.to());
+  }
+}
+```
 
-functionsControl!: IDateDropdownFunctionControlEvent;
+```html
+<!-- filter.component.html -->
+<libs_ui-components-datetime-dropdown
+  [typeFormat]="'year-quarter'"
+  [isMultiple]="true"
+  [listKeysDisable]="disabledKeys"
+  (outChooseMultiDate)="handlerMultiDateSelected($event)"
+/>
+```
 
-onMultiDateSelected(event: IEmitMultiDateDropdown) {
-  console.log('From:', event.from(), 'To:', event.to());
-}
+### 5. Với label và emit liên tục mỗi lần chọn
 
-onFunctionsControl(event: IDateDropdownFunctionControlEvent) {
-  this.functionsControl = event;
+```typescript
+import { Component, signal } from '@angular/core';
+import {
+  LibsUiComponentsDatetimeDropdownComponent,
+  IEmitSingleDateDropdown,
+  IEmitMultiDateDropdown,
+} from '@libs-ui/components-datetime-dropdown';
+import { ILabel } from '@libs-ui/components-label';
+
+@Component({
+  selector: 'app-with-label',
+  standalone: true,
+  imports: [LibsUiComponentsDatetimeDropdownComponent],
+  templateUrl: './with-label.component.html',
+})
+export class WithLabelComponent {
+  readonly labelConfig: ILabel = {
+    labelLeft: 'Kỳ báo cáo',
+    required: true,
+  };
+
+  handlerSelectedDropdown(event: IEmitSingleDateDropdown | IEmitMultiDateDropdown): void {
+    event.stopPropagation();
+    console.log('Giá trị vừa chọn:', event);
+  }
 }
 ```
 
-### 4. With Validation
-
 ```html
 <libs_ui-components-datetime-dropdown
   [typeFormat]="'year-month'"
-  [isMultiple]="true"
-  [validRequired]="{ message: 'i18n_required', messageValidCompareTime: 'i18n_invalid_range' }"
-  [ignoreAllowTimeEqual]="true"
-  [ignoreValidTimeCompare]="false"
-  [isCheckErrorWhenSelectItem]="true"
-  [isBorderError]="isBorderError"
-  (outFunctionsControl)="onFunctionsControl($event)"
-  (outChooseMultiDate)="onMultiDateSelected($event)"
-></libs_ui-components-datetime-dropdown>
+  [labelConfig]="labelConfig"
+  [isEmitAfterChanged]="true"
+  (outSelectedDropdown)="handlerSelectedDropdown($event)"
+/>
 ```
 
+## @Input()
+
+| Input | Type | Default | Mô tả | Ví dụ |
+|---|---|---|---|---|
+| `[classIncludeTextDisplayWhenNoSelect]` | `string \| undefined` | `undefined` | CSS class tùy chỉnh cho text hiển thị khi chưa chọn giá trị | `[classIncludeTextDisplayWhenNoSelect]="'text-gray-400'"` |
+| `[disable]` | `boolean` | `false` | Vô hiệu hóa toàn bộ component | `[disable]="true"` |
+| `[disableSecond]` | `boolean` | `false` | Vô hiệu hóa dropdown thứ hai cho đến khi dropdown đầu tiên được chọn | `[disableSecond]="true"` |
+| `[fromAndToDateLabel]` | `IFromAndToDateLabel` | `{ from: 'i18n_label_from', to: 'i18n_to' }` | Tùy chỉnh label From/To và CSS class của chúng khi `isMultiple=true` | `[fromAndToDateLabel]="{ from: 'Từ', to: 'Đến' }"` |
+| `[getItemYearDisplay]` | `(year: string) => string` | `undefined` | Hàm tùy chỉnh cách hiển thị label năm trong dropdown | `[getItemYearDisplay]="formatYear"` |
+| `[hiddenDate]` | `IHiddenDate \| undefined` | `undefined` | Ẩn các giá trị ngày/tháng cụ thể khỏi danh sách dropdown | `[hiddenDate]="hiddenConfig"` |
+| `[ignoreAllowTimeEqual]` | `boolean` | `true` | Khi `true`: from phải nhỏ hơn to (không cho bằng nhau). Khi `false`: from có thể bằng to | `[ignoreAllowTimeEqual]="false"` |
+| `[ignoreConvertYearSelected]` | `boolean` | `false` | Hiển thị giá trị năm gốc thay vì qua i18n convert | `[ignoreConvertYearSelected]="true"` |
+| `[ignoreFromAndToDateLabel]` | `boolean` | `false` | Ẩn label From/To, chỉ hiển thị dấu `-` ngăn cách | `[ignoreFromAndToDateLabel]="true"` |
+| `[ignoreRequiredValueSecondWhenNotValidRequired]` | `boolean` | `false` | Bỏ qua validate giá trị thứ hai khi `validRequired` không được cấu hình | `[ignoreRequiredValueSecondWhenNotValidRequired]="true"` |
+| `[ignoreValidTimeCompare]` | `boolean` | `false` | Bỏ qua validation so sánh từ/đến (hữu ích khi chỉ cần validate required) | `[ignoreValidTimeCompare]="true"` |
+| `[isBorderError]` | `boolean` | `false` | Hiển thị viền đỏ lỗi trên tất cả dropdown | `[isBorderError]="hasError"` |
+| `[isCheckErrorWhenSelectItem]` | `boolean` | `true` | Tự động kiểm tra và hiển thị lỗi mỗi khi người dùng chọn một item | `[isCheckErrorWhenSelectItem]="false"` |
+| `[isEmitAfterChanged]` | `boolean` | `false` | Emit `outSelectedDropdown` mỗi lần chọn giá trị (kể cả khi chưa chọn đủ). Cần check `undefined` cẩn thận | `[isEmitAfterChanged]="true"` |
+| `[isMultiple]` | `boolean` | `false` | Bật chế độ chọn khoảng thời gian — hiển thị hai nhóm dropdown (From/To) với validation so sánh | `[isMultiple]="true"` |
+| `[labelConfig]` | `ILabel \| undefined` | `undefined` | Cấu hình label phía trên component, dùng `ILabel` từ `@libs-ui/components-label` | `[labelConfig]="{ labelLeft: 'Kỳ báo cáo', required: true }"` |
+| `[listHasButtonUnSelectOption]` | `boolean` | `false` | Hiển thị nút "Bỏ chọn" trong danh sách dropdown | `[listHasButtonUnSelectOption]="true"` |
+| `[listKeysDisable]` | `IDateDropdownDisableKeys \| undefined` | `undefined` | Cấu hình disable từng giá trị (năm/tháng/quý/ngày) cho from và to riêng biệt | `[listKeysDisable]="disabledKeys"` |
+| `[listMaxItemShow]` | `{ year?: number; month?: number; quarter?: number; day?: number } \| undefined` | `undefined` | Giới hạn số lượng item tối đa hiển thị trong dropdown cho từng loại | `[listMaxItemShow]="{ year: 5 }"` |
+| `[maxYear]` | `number` | `0` (dùng DEFAULT_MAX_YEAR từ picker) | Năm tối đa hiển thị trong dropdown năm | `[maxYear]="2030"` |
+| `[minWidth]` | `number \| undefined` | `undefined` | Chiều rộng tối thiểu của toàn bộ component (px) | `[minWidth]="200"` |
+| `[minYear]` | `number` | `0` (dùng DEFAULT_MIN_YEAR từ picker) | Năm tối thiểu hiển thị trong dropdown năm | `[minYear]="2020"` |
+| `[readonly]` | `boolean` | `false` | Chế độ chỉ đọc — hiển thị giá trị nhưng không cho phép thay đổi | `[readonly]="true"` |
+| `[reverseYear]` | `boolean \| undefined` | `undefined` | Đảo ngược thứ tự danh sách năm (năm mới nhất hiển thị trên đầu) | `[reverseYear]="true"` |
+| `[selectedDateTime]` | `IEmitMultiDateDropdown \| undefined` | `undefined` | Giá trị khởi tạo — phải dùng `WritableSignal` bên trong (xem interface `IEmitMultiDateDropdown`) | `[selectedDateTime]="selectedRange"` |
+| `[typeFormat]` | `TYPE_DATE_DROPDOWN_FORMAT` | `'month-day'` | Định dạng dropdown hiển thị: `'year'`, `'month'`, `'quarter'`, `'year-month'`, `'month-day'`, `'year-quarter'` | `[typeFormat]="'year-month'"` |
+| `[validRequired]` | `IValidDateDropdown \| undefined` | `undefined` | Cấu hình validation bắt buộc với message lỗi tùy chỉnh | `[validRequired]="{ message: 'i18n_required' }"` |
+| `[widthByElement]` | `boolean` | `false` | Tự động tính chiều rộng dropdown theo kích thước phần tử cha | `[widthByElement]="true"` |
+| `[widthDropdown]` | `number` | `136` | Chiều rộng (px) của mỗi ô dropdown đơn lẻ | `[widthDropdown]="160"` |
+| `[zIndex]` | `number` | `1200` | z-index của dropdown overlay khi mở | `[zIndex]="1300"` |
+
+## @Output()
+
+| Output | Type | Mô tả | Handler TS | Binding HTML |
+|---|---|---|---|---|
+| `(outChangStageFlagMouse)` | `IFlagMouse` | Emit khi trạng thái chuột thay đổi (hover/leave trên dropdown) | `handlerFlagMouseChange(event: IFlagMouse): void { event.stopPropagation(); ... }` | `(outChangStageFlagMouse)="handlerFlagMouseChange($event)"` |
+| `(outChooseMultiDate)` | `IEmitMultiDateDropdown` | Emit khi người dùng chọn đầy đủ cả From và To (chỉ khi `isMultiple=true`). Chỉ emit khi cả hai hợp lệ | `handlerMultiDateSelected(event: IEmitMultiDateDropdown): void { event.stopPropagation(); ... }` | `(outChooseMultiDate)="handlerMultiDateSelected($event)"` |
+| `(outChooseSingleDate)` | `IEmitSingleDateDropdown` | Emit khi người dùng chọn đầy đủ tất cả các trường theo `typeFormat` (chỉ khi `isMultiple=false`) | `handlerSingleDateSelected(event: IEmitSingleDateDropdown): void { event.stopPropagation(); ... }` | `(outChooseSingleDate)="handlerSingleDateSelected($event)"` |
+| `(outFunctionsControl)` | `IDateDropdownFunctionControlEvent` | Emit object chứa các hàm điều khiển component từ bên ngoài. Được emit một lần trong `ngOnInit` | `handlerFunctionsControl(event: IDateDropdownFunctionControlEvent): void { event.stopPropagation(); this.ctrl = event; }` | `(outFunctionsControl)="handlerFunctionsControl($event)"` |
+| `(outSelectedDropdown)` | `IEmitSingleDateDropdown \| IEmitMultiDateDropdown` | Emit mỗi khi người dùng chọn bất kỳ giá trị nào. Chỉ hoạt động khi `isEmitAfterChanged=true`. Lưu ý: cần kiểm tra `undefined` kỹ khi sử dụng | `handlerSelectedDropdown(event: IEmitSingleDateDropdown \| IEmitMultiDateDropdown): void { event.stopPropagation(); ... }` | `(outSelectedDropdown)="handlerSelectedDropdown($event)"` |
+
+## FunctionsControl (IDateDropdownFunctionControlEvent)
+
+Nhận qua `(outFunctionsControl)`, dùng để điều khiển component từ bên ngoài (thường là từ nút Submit/Reset của form).
+
+| Method | Signature | Mô tả |
+|---|---|---|
+| `checkIsValid()` | `() => Promise<boolean>` | Kiểm tra toàn bộ validation (required + so sánh from/to). Trả về `false` nếu có lỗi và hiển thị trạng thái lỗi trên UI |
+| `resetError()` | `() => Promise<void>` | Xóa tất cả trạng thái lỗi đang hiển thị trên component |
+| `resetTime()` | `() => Promise<void>` | Reset toàn bộ giá trị đã chọn về trạng thái trống |
+
 ```typescript
-async onSubmit() {
-  const isValid = await this.functionsControl.checkIsValid();
+// Sử dụng FunctionsControl trong form submit
+private dropdownControl?: IDateDropdownFunctionControlEvent;
+
+handlerFunctionsControl(event: IDateDropdownFunctionControlEvent): void {
+  event.stopPropagation();
+  this.dropdownControl = event;
+}
+
+async handlerSubmit(): Promise<void> {
+  const isValid = await this.dropdownControl?.checkIsValid();
   if (!isValid) {
-    return;
+    return; // dừng lại nếu có lỗi
   }
-  // Tiến hành submit
+  // tiến hành submit
 }
 
-resetForm() {
-  this.functionsControl.resetTime?.();
-  this.functionsControl.resetError?.();
+async handlerReset(): Promise<void> {
+  await this.dropdownControl?.resetTime?.();
+  await this.dropdownControl?.resetError?.();
 }
 ```
 
-## API Reference
-
-### Inputs
-
-| Tên | Kiểu | Mặc định | Mô tả |
-| --- | --- | --- | --- |
-| `[classIncludeTextDisplayWhenNoSelect]` | `string \| undefined` | `undefined` | CSS class tùy chỉnh text hiển thị khi chưa chọn giá trị |
-| `[disable]` | `boolean` | `false` | Vô hiệu hóa toàn bộ component |
-| `[disableSecond]` | `boolean` | `false` | Vô hiệu hóa dropdown thứ hai cho đến khi dropdown đầu tiên được chọn |
-| `[fromAndToDateLabel]` | `IFromAndToDateLabel` | `{ from: 'i18n_label_from', to: 'i18n_to' }` | Tùy chỉnh label From/To khi `isMultiple=true` |
-| `[getItemYearDisplay]` | `(year: string) => string` | — | Hàm tùy chỉnh hiển thị label cho item năm |
-| `[hiddenDate]` | `IHiddenDate \| undefined` | `undefined` | Ẩn các giá trị ngày/tháng cụ thể khỏi dropdown |
-| `[ignoreAllowTimeEqual]` | `boolean` | `true` | Bỏ qua cho phép thời gian bằng nhau khi so sánh from/to. `true` = from phải nhỏ hơn to (không cho bằng) |
-| `[ignoreConvertYearSelected]` | `boolean` | `false` | Bỏ qua chuyển đổi label năm đã chọn (hiển thị raw value) |
-| `[ignoreFromAndToDateLabel]` | `boolean` | `false` | Ẩn label From/To khi `isMultiple=true` |
-| `[ignoreRequiredValueSecondWhenNotValidRequired]` | `boolean` | `false` | Bỏ qua validate giá trị thứ 2 khi `validRequired` không được set |
-| `[ignoreValidTimeCompare]` | `boolean` | `false` | Bỏ qua validation so sánh thời gian from/to |
-| `[isBorderError]` | `boolean` | `false` | Hiển thị viền lỗi trên component |
-| `[isCheckErrorWhenSelectItem]` | `boolean` | `true` | Kiểm tra lỗi mỗi khi chọn item |
-| `[isEmitAfterChanged]` | `boolean` | `false` | Emit `outSelectedDropdown` mỗi lần chọn giá trị (bao gồm lần đầu init) |
-| `[isMultiple]` | `boolean` | `false` | Chế độ multi selection (From/To) — hiển thị 2 nhóm dropdown |
-| `[labelConfig]` | `ILabel \| undefined` | `undefined` | Cấu hình label (từ `@libs-ui/components-label`) |
-| `[listHasButtonUnSelectOption]` | `boolean` | `false` | Hiển thị nút bỏ chọn trong dropdown list |
-| `[listKeysDisable]` | `IDateDropdownDisableKeys \| undefined` | `undefined` | Danh sách key bị vô hiệu hóa cho từng dropdown (from/to) |
-| `[listMaxItemShow]` | `{ year?: number; month?: number; quarter?: number; day?: number } \| undefined` | `undefined` | Giới hạn số item hiển thị cho từng loại dropdown |
-| `[maxYear]` | `number` | `0` (sử dụng DEFAULT_MAX_YEAR) | Năm tối đa hiển thị trong dropdown năm |
-| `[minWidth]` | `number \| undefined` | `undefined` | Chiều rộng tối thiểu của component (px) |
-| `[minYear]` | `number` | `0` (sử dụng DEFAULT_MIN_YEAR) | Năm tối thiểu hiển thị trong dropdown năm |
-| `[readonly]` | `boolean` | `false` | Chế độ chỉ đọc |
-| `[reverseYear]` | `boolean \| undefined` | `undefined` | Đảo ngược thứ tự danh sách năm (năm mới nhất lên đầu) |
-| `[selectedDateTime]` | `IEmitMultiDateDropdown \| undefined` | `undefined` | Giá trị khởi tạo — sử dụng `WritableSignal` bên trong |
-| `[typeFormat]` | `TYPE_DATE_DROPDOWN_FORMAT` | `'month-day'` | Loại format hiển thị: `'year'`, `'month'`, `'quarter'`, `'year-month'`, `'month-day'`, `'year-quarter'` |
-| `[validRequired]` | `IValidDateDropdown` | — | Cấu hình validation bắt buộc với message lỗi tùy chỉnh |
-| `[widthByElement]` | `boolean` | `false` | Tính width dropdown theo phần tử cha |
-| `[widthDropdown]` | `number` | `136` | Chiều rộng mỗi dropdown (px) |
-| `[zIndex]` | `number` | `1200` | z-index của dropdown overlay |
-
-### Outputs
-
-| Tên | Kiểu | Mô tả |
-| --- | --- | --- |
-| `(outChangStageFlagMouse)` | `EventEmitter<IFlagMouse>` | Emit khi trạng thái chuột thay đổi (hover/leave) |
-| `(outChooseMultiDate)` | `EventEmitter<IEmitMultiDateDropdown>` | Emit khi chọn đầy đủ cả From và To (chỉ khi `isMultiple=true`) |
-| `(outChooseSingleDate)` | `EventEmitter<IEmitSingleDateDropdown>` | Emit khi chọn đầy đủ single date (chỉ khi `isMultiple=false`) |
-| `(outFunctionsControl)` | `EventEmitter<IDateDropdownFunctionControlEvent>` | Emit object chứa các hàm điều khiển component từ bên ngoài |
-| `(outSelectedDropdown)` | `EventEmitter<IEmitSingleDateDropdown \| IEmitMultiDateDropdown>` | Emit mỗi lần chọn giá trị (cần `isEmitAfterChanged=true`). Lưu ý: cần check `undefined` kỹ khi sử dụng |
-
-### FunctionsControl Methods
-
-Object nhận được từ `(outFunctionsControl)`:
-
-| Method | Kiểu trả về | Mô tả |
-| --- | --- | --- |
-| `checkIsValid()` | `Promise<boolean>` | Kiểm tra validation toàn bộ component. Trả về `false` nếu có lỗi required hoặc lỗi so sánh from/to |
-| `resetError()` | `Promise<void>` | Xóa tất cả trạng thái lỗi hiển thị trên component |
-| `resetTime()` | `Promise<void>` | Reset toàn bộ giá trị đã chọn về trạng thái ban đầu |
-
 ## Types & Interfaces
 
+```typescript
+import {
+  TYPE_DATE_DROPDOWN_FORMAT,
+  TYPE_DATE_FORMAT,
+  IEmitSingleDateDropdown,
+  IEmitMultiDateDropdown,
+  IFromAndToDateLabel,
+  IDateDropdownFunctionControlEvent,
+  IValidDateDropdown,
+  IHiddenDate,
+  IDateDropdownDisableKeys,
+  IDateDropdownDisable,
+} from '@libs-ui/components-datetime-dropdown';
+```
+
 ### TYPE_DATE_DROPDOWN_FORMAT
 
+Format truyền vào `[typeFormat]` — quyết định dropdown nào xuất hiện:
+
 ```typescript
-type TYPE_DATE_DROPDOWN_FORMAT = 'year' | 'month' | 'quarter' | 'year-month' | 'month-day' | 'year-quarter' | string;
+type TYPE_DATE_DROPDOWN_FORMAT =
+  | 'year'          // 1 dropdown: năm
+  | 'month'         // 1 dropdown: tháng
+  | 'quarter'       // 1 dropdown: quý
+  | 'year-month'    // 2 dropdown: năm + tháng
+  | 'month-day'     // 2 dropdown: tháng + ngày (mặc định)
+  | 'year-quarter'  // 2 dropdown: năm + quý
+  | string;         // custom format (ít dùng)
 ```
 
 ### TYPE_DATE_FORMAT
@@ -226,6 +417,8 @@ type TYPE_DATE_FORMAT = 'year' | 'month' | 'quarter' | 'day';
 
 ### IEmitSingleDateDropdown
 
+Dữ liệu emit khi chọn single date (qua `outChooseSingleDate`). Chỉ có các trường tương ứng với `typeFormat`:
+
 ```typescript
 interface IEmitSingleDateDropdown {
   year?: number;
@@ -233,15 +426,32 @@ interface IEmitSingleDateDropdown {
   quarter?: number;
   day?: number;
 }
+
+// Ví dụ: typeFormat="year-month" → { year: 2024, month: 6 }
+// Ví dụ: typeFormat="month-day"  → { month: 3, day: 15 }
+// Ví dụ: typeFormat="year"       → { year: 2024 }
 ```
 
 ### IEmitMultiDateDropdown
 
+Dữ liệu khởi tạo (`selectedDateTime`) và emit khi chọn multi date (`outChooseMultiDate`). Dùng `WritableSignal`:
+
 ```typescript
 interface IEmitMultiDateDropdown {
   from: WritableSignal<IEmitSingleDateDropdown>;
   to: WritableSignal<IEmitSingleDateDropdown>;
 }
+
+// Tạo giá trị khởi tạo:
+import { signal } from '@angular/core';
+const selectedRange: IEmitMultiDateDropdown = {
+  from: signal<IEmitSingleDateDropdown>({ year: 2024, month: 1 }),
+  to: signal<IEmitSingleDateDropdown>({ year: 2024, month: 12 }),
+};
+
+// Đọc giá trị:
+console.log(event.from()); // { year: 2024, month: 1 }
+console.log(event.to());   // { year: 2024, month: 12 }
 ```
 
 ### IDateDropdownFunctionControlEvent
@@ -256,28 +466,38 @@ interface IDateDropdownFunctionControlEvent {
 
 ### IValidDateDropdown
 
+Cấu hình message lỗi cho validation. Dùng với i18n key:
+
 ```typescript
 interface IValidDateDropdown {
-  message?: string;
-  interpolateParams?: { any: object };
-  messageValidCompareTime?: string;
-  interpolateParamsCompareTime?: { any: object };
+  message?: string;                           // i18n key cho lỗi required
+  interpolateParams?: { any: object };         // params cho message
+  messageValidCompareTime?: string;            // i18n key cho lỗi so sánh from > to
+  interpolateParamsCompareTime?: { any: object }; // params cho messageValidCompareTime
 }
+
+// Ví dụ:
+const validRequired: IValidDateDropdown = {
+  message: 'i18n_required',
+  messageValidCompareTime: 'i18n_invalid_end_date_selected',
+};
 ```
 
 ### IFromAndToDateLabel
 
 ```typescript
 interface IFromAndToDateLabel {
-  to?: string;
-  from?: string;
-  classLabelTo?: string;
-  classLabelFrom?: string;
+  from?: string;          // i18n key hoặc text trực tiếp cho label "From"
+  to?: string;            // i18n key hoặc text trực tiếp cho label "To"
+  classLabelFrom?: string; // CSS class tùy chỉnh cho label "From"
+  classLabelTo?: string;   // CSS class tùy chỉnh cho label "To"
 }
 ```
 
 ### IDateDropdownDisableKeys
 
+Cấu hình disable từng giá trị cho from và to riêng biệt:
+
 ```typescript
 interface IDateDropdownDisableKeys {
   from?: WritableSignal<IDateDropdownDisable>;
@@ -290,30 +510,52 @@ interface IDateDropdownDisable {
   quarter?: WritableSignal<Array<number>>;
   day?: WritableSignal<Array<number>>;
 }
+
+// Ví dụ: disable tháng 1 và tháng 2 cho "from"
+import { signal } from '@angular/core';
+const disabledKeys: IDateDropdownDisableKeys = {
+  from: signal({
+    month: signal([1, 2]),
+  }),
+};
 ```
 
 ### IHiddenDate
 
+Ẩn hoàn toàn các giá trị cụ thể khỏi danh sách dropdown:
+
 ```typescript
 interface IHiddenDate {
   formatDate: TYPE_DATE_DROPDOWN_FORMAT;
-  yearMonth?: WritableSignal<Array<WritableSignal<{ hiddenYear: number; hiddenMonths: Array<number> }>>>;
-  monthDay?: WritableSignal<Array<WritableSignal<{ hiddenMonth: number; hiddenDays: Array<number> }>>>;
+  yearMonth?: WritableSignal<Array<WritableSignal<{
+    hiddenYear: number;
+    hiddenMonths: Array<number>;
+  }>>>;
+  monthDay?: WritableSignal<Array<WritableSignal<{
+    hiddenMonth: number;
+    hiddenDays: Array<number>;
+  }>>>;
 }
 ```
 
-## Tùy chỉnh style
+## Lưu ý quan trọng
 
-- Sử dụng `[classIncludeTextDisplayWhenNoSelect]` để tùy chỉnh text display khi chưa chọn giá trị
-- Sử dụng `[widthDropdown]` để điều chỉnh chiều rộng mỗi dropdown (mặc định `136px`)
-- Sử dụng `[fromAndToDateLabel]` để tùy chỉnh label From/To, bao gồm cả CSS class qua `classLabelFrom` và `classLabelTo`
+⚠️ **selectedDateTime dùng WritableSignal**: Input `[selectedDateTime]` nhận `IEmitMultiDateDropdown` trong đó `from` và `to` là `WritableSignal`. Phải khởi tạo đúng: `{ from: signal({ year: 2024 }), to: signal({ year: 2024 }) }`.
 
-## Demo
+⚠️ **typeFormat quyết định số dropdown**: `'year-month'` tạo 2 dropdown (năm + tháng), `'year'` tạo 1 dropdown. Output event chỉ có các trường tương ứng với format đã chọn.
+
+⚠️ **outChooseMultiDate chỉ emit khi đầy đủ**: Ở multi mode, `outChooseMultiDate` chỉ emit khi cả from và to đều được chọn đầy đủ. Nếu cần emit từng lần chọn, dùng `[isEmitAfterChanged]="true"` kết hợp `(outSelectedDropdown)`.
+
+⚠️ **outSelectedDropdown cần check undefined**: Khi dùng `[isEmitAfterChanged]="true"`, output `(outSelectedDropdown)` có thể emit giá trị chưa đầy đủ. Luôn kiểm tra các trường trước khi sử dụng.
 
-- Local: [http://localhost:4500/datetime/dropdown](http://localhost:4500/datetime/dropdown)
+⚠️ **ignoreAllowTimeEqual mặc định true**: Mặc định from phải nhỏ hơn to (không cho bằng nhau). Đặt `[ignoreAllowTimeEqual]="false"` nếu muốn cho phép from = to.
 
-## Test
+⚠️ **widthDropdown áp dụng cho từng dropdown đơn**: Khi `typeFormat="year-month"` và `widthDropdown=136`, tổng chiều rộng sẽ là khoảng `136 * 2 + spacing`. Dùng `[widthByElement]="true"` để component tự tính theo container cha.
+
+## Demo
 
 ```bash
-npx nx test components-datetime-dropdown
+npx nx serve core-ui
 ```
+
+Truy cập: http://localhost:4500/datetime/dropdown