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

package/README.md

@@ -1,139 +1,431 @@
 # @libs-ui/components-popover
 
-> Component hiển thị nội dung nổi (popover/tooltip) gắn liền với một phần tử gốc, hỗ trợ nhiều hướng và chế độ kích hoạt.
+> Component/Directive hiển thị nội dung nổi (popover/tooltip) gắn liền với phần tử gốc, tự động định vị thông minh, hỗ trợ nhiều chế độ kích hoạt và nội dung tùy chỉnh.
 
 ## Giới thiệu
 
-Bộ công cụ Popover cung cấp giải pháp hiển thị thông tin ngữ cảnh linh hoạt. Bạn có thể sử dụng nó dưới dạng `Directive` để tiết kiệm DOM hoặc `Component Selector` khi cần bọc nhiều phần tử phức tạp.
+`@libs-ui/components-popover` cung cấp giải pháp hiển thị thông tin ngữ cảnh linh hoạt trong ứng dụng Angular. Lib hỗ trợ cả hai cách dùng: dạng **Directive** gắn trực tiếp vào phần tử HTML bất kỳ, hoặc dạng **Component Selector** để bọc nội dung phức tạp. Popover tự động tính toán vị trí tối ưu dựa trên viewport, fallback sang hướng khác nếu không đủ chỗ, và tự dọn dẹp khi component bị destroy.
 
-### Tính năng
+## Tính năng
 
-- ✅ **Linh hoạt cách dùng**: Hỗ trợ cả Directive và Component Selector.
-- ✅ **Định vị thông minh**: Tự động tính toán hướng để không bị tràn khung nhìn (viewport).
-- ✅ **Template Support**: Hỗ trợ hiển thị nội dung từ `string` đơn giản đến `ng-template` phức tạp.
-- ✅ **Event Handling**: Quản lý tốt các sự kiện hover, click và click-outside.
-- ✅ **Customizable**: Dễ dàng tùy chỉnh chiều rộng, class CSS và hướng hiển thị.
-- ✅ **OnPush Change Detection**
-- ✅ **Angular Signals**
+- ✅ **Hai cách dùng**: Directive (`[LibsUiComponentsPopoverDirective]`) và Component Selector (`libs_ui-components-popover`)
+- ✅ **Tự động định vị thông minh**: Tính toán hướng tốt nhất dựa trên viewport, tự fallback nếu bị tràn
+- ✅ **Nhiều chế độ kích hoạt**: `hover`, `click`, `click-toggle`, `click_open_and_click_panel_content_hidden`
+- ✅ **Hỗ trợ `ng-template`**: Truyền nội dung phức tạp qua `TemplateRef`
+- ✅ **Chế độ text-ellipsis**: Chỉ hiển thị khi text bị cắt ngắn (`type="text"`)
+- ✅ **FunctionControl API**: Điều khiển popover từ bên ngoài qua `outFunctionsControl`
+- ✅ **Hỗ trợ iframe**: Render popover vào parent document khi chạy trong iframe
+- ✅ **Tự cleanup**: Tự dọn dẹp overlay khi component bị destroy, không memory leak
+- ✅ **OnPush + Angular Signals**
 
 ## Khi nào sử dụng
 
-- Hiển thị thông tin bổ sung (Tooltips) khi di chuột qua phần tử.
-- Hiển thị menu hoặc nội dung chi tiết khi nhấn vào nút.
-- Thông báo trạng thái hoặc hướng dẫn người dùng tại chỗ.
+- Hiển thị tooltip thông tin bổ sung khi di chuột qua icon hoặc văn bản bị truncate
+- Hiển thị dropdown menu hoặc panel tùy chọn khi nhấn vào nút
+- Hiển thị card chi tiết (user profile, product info) khi hover
+- Xây dựng các component dropdown tùy chỉnh cần định vị thông minh
+- Thông báo hướng dẫn, hint tại chỗ cho người dùng
 
 ## Cài đặt
 
 ```bash
-# npm
 npm install @libs-ui/components-popover
-
-# yarn
-yarn add @libs-ui/components-popover
 ```
 
 ## Import
 
 ```typescript
-import { LibsUiComponentsPopoverModule } from '@libs-ui/components-popover';
+import { LibsUiComponentsPopoverComponent } from '@libs-ui/components-popover';
 
 @Component({
   standalone: true,
-  imports: [LibsUiComponentsPopoverModule],
+  imports: [LibsUiComponentsPopoverComponent],
   // ...
 })
 export class YourComponent {}
 ```
 
-## Ví dụ
+> **Lưu ý**: `LibsUiComponentsPopoverComponent` bao gồm cả selector dạng Directive (`[LibsUiComponentsPopoverDirective]`). Chỉ cần import một lần cho cả hai cách dùng.
+
+## Ví dụ sử dụng
 
-### Directive (Sử dụng phổ biến)
+### Ví dụ 1 — Dạng Directive (Tooltip đơn giản)
 
-```html
-<div
-  LibsUiComponentsPopoverDirective
-  [config]="{ content: 'Nội dung thông báo' }">
-  Hover me
-</div>
+```typescript
+import { LibsUiComponentsPopoverComponent } from '@libs-ui/components-popover';
+
+@Component({
+  standalone: true,
+  imports: [LibsUiComponentsPopoverComponent],
+  template: `
+    <span
+      LibsUiComponentsPopoverDirective
+      [config]="{ content: 'Tên đầy đủ: Nguyễn Văn A', direction: 'bottom' }">
+      Nguyễn V. A
+    </span>
+  `,
+})
+export class BasicTooltipComponent {}
 ```
 
-### Component Selector
+### Ví dụ 2 — Dạng Component Selector với nội dung phức tạp
 
-```html
-<libs_ui-components-popover [config]="{ content: 'Nội dung thông báo', direction: 'top' }">
-  <button>Action</button>
-</libs_ui-components-popover>
+```typescript
+import { LibsUiComponentsPopoverComponent } from '@libs-ui/components-popover';
+import { IPopoverFunctionControlEvent } from '@libs-ui/components-popover';
+
+@Component({
+  standalone: true,
+  imports: [LibsUiComponentsPopoverComponent],
+  template: `
+    <libs_ui-components-popover
+      [config]="popoverConfig"
+      [mode]="'click-toggle'"
+      (outEvent)="handlerPopoverEvent($event)"
+      (outFunctionsControl)="handlerFunctionsControl($event)">
+      <button class="px-4 py-2 bg-blue-600 text-white rounded">
+        Mở menu
+      </button>
+    </libs_ui-components-popover>
+  `,
+})
+export class ClickPopoverComponent {
+  protected popoverConfig = {
+    content: 'Nội dung menu',
+    direction: 'bottom' as const,
+    maxWidth: 200,
+  };
+
+  private popoverControl?: IPopoverFunctionControlEvent;
+
+  handlerFunctionsControl(control: IPopoverFunctionControlEvent): void {
+    event?.stopPropagation();
+    this.popoverControl = control;
+  }
+
+  handlerPopoverEvent(event: string): void {
+    event?.stopPropagation();
+    console.log('Popover event:', event);
+  }
+
+  closePopover(): void {
+    this.popoverControl?.removePopoverOverlay();
+  }
+}
+```
+
+### Ví dụ 3 — Dùng ng-template cho nội dung tùy chỉnh
+
+```typescript
+import { LibsUiComponentsPopoverComponent } from '@libs-ui/components-popover';
+
+@Component({
+  standalone: true,
+  imports: [LibsUiComponentsPopoverComponent],
+  template: `
+    <div
+      LibsUiComponentsPopoverDirective
+      [config]="{ template: profileTpl, maxWidth: 280, direction: 'right' }">
+      <img src="avatar.png" alt="Avatar" class="w-10 h-10 rounded-full cursor-pointer" />
+    </div>
+
+    <ng-template #profileTpl>
+      <div class="p-4">
+        <div class="font-bold text-gray-800">Nguyễn Văn A</div>
+        <div class="text-sm text-gray-500">nguyenvana@example.com</div>
+        <hr class="my-3" />
+        <button class="text-sm text-red-500">Đăng xuất</button>
+      </div>
+    </ng-template>
+  `,
+})
+export class ProfilePopoverComponent {}
 ```
 
-## API
+### Ví dụ 4 — Chế độ text-ellipsis (chỉ hiện khi text bị cắt)
 
-### LibsUiComponentsPopoverDirective / LibsUiComponentsPopoverComponent
+```typescript
+import { LibsUiComponentsPopoverComponent } from '@libs-ui/components-popover';
 
-#### Inputs
+@Component({
+  standalone: true,
+  imports: [LibsUiComponentsPopoverComponent],
+  template: `
+    <div
+      LibsUiComponentsPopoverDirective
+      [type]="'text'"
+      [config]="{ content: 'Đây là đoạn văn bản dài sẽ bị cắt ngắn khi container quá nhỏ', direction: 'top' }"
+      style="width: 120px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;">
+      Đây là đoạn văn bản dài sẽ bị cắt ngắn khi container quá nhỏ
+    </div>
+  `,
+})
+export class TextEllipsisPopoverComponent {}
+```
 
-| Property                             | Type                           | Default      | Description                                              |
-| ------------------------------------ | ------------------------------ | ------------ | -------------------------------------------------------- |
-| `[config]`                           | `IPopoverConfig`               | **Bắt buộc** | Cấu hình nội dung, hướng và kích thước của popover.      |
-| `[mode]`                             | `'hover' \| 'click' \| 'none'` | `'hover'`    | Chế độ kích hoạt hiển thị.                               |
-| `[ignoreCursorPointerModeLikeClick]` | `boolean`                      | `false`      | Bỏ qua việc đổi cursor thành pointer trong chế độ click. |
-| `[ignoreStopPropagationEvent]`       | `boolean`                      | `false`      | Cho phép sự kiện click lan truyền ra lớp cha.            |
-| `[initEventInElementRefCustom]`      | `ElementRef`                   | `undefined`  | Gắn sự kiện vào một element khác thay vì host element.   |
+### Ví dụ 5 — Điều khiển từ bên ngoài (FunctionControl)
 
-#### Outputs
+```typescript
+import { LibsUiComponentsPopoverComponent } from '@libs-ui/components-popover';
+import { IPopoverFunctionControlEvent } from '@libs-ui/components-popover';
 
-| Property        | Type      | Description                             |
-| --------------- | --------- | --------------------------------------- |
-| `(outExpanded)` | `boolean` | Phát ra trạng thái đóng/mở của popover. |
+@Component({
+  standalone: true,
+  imports: [LibsUiComponentsPopoverComponent],
+  template: `
+    <libs_ui-components-popover
+      [config]="{ content: 'Popover được mở từ bên ngoài', direction: 'bottom' }"
+      [mode]="'click'"
+      [ignoreShowPopover]="true"
+      (outFunctionsControl)="handlerFunctionsControl($event)">
+      <span>Phần tử target</span>
+    </libs_ui-components-popover>
+
+    <button (click)="handlerOpenPopover($event)">Mở Popover từ nút khác</button>
+    <button (click)="handlerClosePopover($event)">Đóng Popover</button>
+  `,
+})
+export class ControlledPopoverComponent {
+  private popoverControl?: IPopoverFunctionControlEvent;
+
+  handlerFunctionsControl(control: IPopoverFunctionControlEvent): void {
+    event?.stopPropagation();
+    this.popoverControl = control;
+  }
+
+  handlerOpenPopover(event: MouseEvent): void {
+    event.stopPropagation();
+    this.popoverControl?.showPopover();
+  }
+
+  handlerClosePopover(event: MouseEvent): void {
+    event.stopPropagation();
+    this.popoverControl?.removePopoverOverlay();
+  }
+}
+```
+
+## @Input()
+
+| Input | Type | Default | Mô tả | Ví dụ |
+|---|---|---|---|---|
+| `[config]` | `IPopoverOverlay` | `{}` | Cấu hình nội dung, hướng, kích thước và style của popover. Bắt buộc truyền để popover hiển thị. | `[config]="{ content: 'Hello', direction: 'top' }"` |
+| `[mode]` | `TYPE_POPOVER_MODE` | `'hover'` | Chế độ kích hoạt hiển thị popover. Xem bảng `TYPE_POPOVER_MODE` bên dưới. | `[mode]="'click-toggle'"` |
+| `[type]` | `'text' \| 'other'` | `'other'` | Khi là `'text'`, popover chỉ hiển thị khi nội dung bị truncate (clientWidth >= scrollWidth). | `[type]="'text'"` |
+| `[ignoreShowPopover]` | `boolean` | `undefined` | Khi `true`, vô hiệu hóa hoàn toàn việc hiển thị popover. Hữu ích khi muốn kiểm soát thủ công qua FunctionControl. | `[ignoreShowPopover]="isDisabled()"` |
+| `[elementRefCustom]` | `HTMLElement` | `undefined` | Element tùy chỉnh để gắn popover vào thay vì host element mặc định. | `[elementRefCustom]="myElementRef"` |
+| `[initEventInElementRefCustom]` | `boolean` | `false` | Khi `true`, gắn event listener vào `elementRefCustom` thay vì host element. Phải dùng kèm `elementRefCustom`. | `[initEventInElementRefCustom]="true"` |
+| `[classInclude]` | `string` | `''` | Các CSS class bổ sung sẽ được thêm vào host element. | `[classInclude]="'cursor-pointer text-blue-500'"` |
+| `[flagMouse]` | `IFlagMouse` | `{ isMouseEnter: false, isMouseEnterContent: false, isContainerHasScroll: false }` | Trạng thái chuột từ component cha, dùng để ngăn đóng popover khi chuột còn trong vùng liên quan. | `[flagMouse]="parentFlagMouse()"` |
+| `[ignoreHiddenPopoverContentWhenMouseLeave]` | `boolean` | `undefined` | Khi `true`, không ẩn popover khi chuột rời khỏi content overlay. | `[ignoreHiddenPopoverContentWhenMouseLeave]="true"` |
+| `[ignoreClickOutside]` | `boolean` | `undefined` | Khi `true`, không đóng popover khi click bên ngoài vùng popover. | `[ignoreClickOutside]="true"` |
+| `[ignoreStopPropagationEvent]` | `boolean` | `undefined` | Khi `true`, không gọi `stopPropagation` trên các event — cho phép event lan truyền lên component cha. | `[ignoreStopPropagationEvent]="true"` |
+| `[ignoreCursorPointerModeLikeClick]` | `boolean` | `undefined` | Khi `true`, không thêm class `cursor-pointer` vào host element khi `mode` là click. | `[ignoreCursorPointerModeLikeClick]="true"` |
+| `[isAddContentToParentDocument]` | `boolean` | `undefined` | Khi `true`, render overlay vào parent document. Dùng khi popover nằm trong iframe. | `[isAddContentToParentDocument]="true"` |
+| `[debugId]` | `string` | `undefined` | ID dùng cho mục đích debug. | `[debugId]="'user-avatar-popover'"` |
+
+## @Output()
+
+| Output | Type | Mô tả | Handler TS | Binding HTML |
+|---|---|---|---|---|
+| `(outEvent)` | `TYPE_POPOVER_EVENT` | Phát ra khi popover thay đổi trạng thái: `'show'` khi mở, `'remove'` khi đóng, `'click'` khi click vào host, `'mouseenter-element'`/`'mouseleave-element'` khi chuột vào/ra khỏi host, `'mouseenter-content'`/`'mouseleave-content'` khi chuột vào/ra khỏi overlay. | `handlerEvent(event: TYPE_POPOVER_EVENT): void { event?.stopPropagation(); ... }` | `(outEvent)="handlerEvent($event)"` |
+| `(outChangStageFlagMouse)` | `IFlagMouse` | Phát ra mỗi khi trạng thái chuột thay đổi. Truyền kết quả vào `[flagMouse]` của popover khác để đồng bộ nhiều popover liên quan. | `handlerFlagMouseChange(flag: IFlagMouse): void { event?.stopPropagation(); this.flagMouse.set(flag); }` | `(outChangStageFlagMouse)="handlerFlagMouseChange($event)"` |
+| `(outEventPopoverContent)` | `TYPE_POPOVER_DIRECTION` | Phát ra hướng thực tế mà popover đang hiển thị sau khi tính toán. Hữu ích để điều chỉnh UI dựa trên vị trí overlay. | `handlerDirectionChange(dir: TYPE_POPOVER_DIRECTION): void { event?.stopPropagation(); this.currentDirection.set(dir); }` | `(outEventPopoverContent)="handlerDirectionChange($event)"` |
+| `(outFunctionsControl)` | `IPopoverFunctionControlEvent` | Phát ra object chứa các hàm điều khiển popover từ bên ngoài. Nhận về ngay khi component khởi tạo. | `handlerFunctionsControl(ctrl: IPopoverFunctionControlEvent): void { event?.stopPropagation(); this.popoverCtrl = ctrl; }` | `(outFunctionsControl)="handlerFunctionsControl($event)"` |
 
 ## Types & Interfaces
 
 ```typescript
-export interface IPopoverConfig {
-  content?: string;
-  template?: TemplateRef<any>;
-  direction?: 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-  width?: number;
-  classCustom?: string;
-  context?: any;
+import {
+  IPopoverOverlay,
+  IPopoverFunctionControlEvent,
+  IFlagMouse,
+  IPopover,
+  TYPE_POPOVER_TYPE,
+  TYPE_POPOVER_MODE,
+  TYPE_POPOVER_DIRECTION,
+  TYPE_POPOVER_POSITION_MODE,
+  TYPE_POPOVER_EVENT,
+} from '@libs-ui/components-popover';
+```
+
+### `IPopoverOverlay` — Cấu hình overlay
+
+```typescript
+import { IPopoverOverlay } from '@libs-ui/components-popover';
+
+export interface IPopoverOverlay {
+  // Nội dung
+  content?: string;               // Nội dung dạng string HTML. Không dùng kèm template.
+  template?: TemplateRef<any>;    // Nội dung dạng ng-template. Không dùng kèm content.
+  itemContext?: any;              // Context truyền vào template khi dùng ng-template.
+
+  // Kích thước
+  width?: number;                 // Chiều rộng cố định (px)
+  minWidth?: number;              // Chiều rộng tối thiểu (px)
+  maxWidth?: number;              // Chiều rộng tối đa (px). Default: 250
+  maxHeight?: number | null;      // Chiều cao tối đa (px). null = tự tính theo viewport. Default: 140
+  widthByParent?: boolean;        // Nếu true, overlay rộng bằng phần tử cha
+  parentBorderWidth?: number;     // Bù border của phần tử cha khi dùng widthByParent
+
+  // Vị trí & hướng
+  direction?: TYPE_POPOVER_DIRECTION;  // Hướng ưu tiên. Default: 'bottom'
+  directionDistance?: number;          // Khoảng cách bổ sung theo hướng (px)
+  position?: {
+    mode: TYPE_POPOVER_POSITION_MODE;  // Căn chỉnh theo trục phụ: 'start' | 'center' | 'end'
+    distance: number;                  // Khoảng offset so với vị trí căn chỉnh (px)
+    autoUpdatePosition?: {
+      startDistance: number;           // Offset khi mode tự chuyển sang 'start'
+      endDistance: number;             // Offset khi mode tự chuyển sang 'end'
+    };
+  };
+
+  // Padding nội dung overlay
+  paddingTop?: number;
+  paddingRight?: number;
+  paddingBottom?: number;
+  paddingLeft?: number;
+
+  // Styling
+  classInclude?: string;           // CSS class bổ sung cho wrapper overlay
+  classIncludeOverlayBody?: string; // CSS class bổ sung cho body overlay
+  whiteTheme?: boolean;            // Dùng theme màu trắng
+  ngStyles?: Record<string, any>;  // Inline styles bổ sung
+
+  // Mũi tên
+  ignoreArrow?: boolean;           // Ẩn mũi tên chỉ hướng
+  arrowPositionCustom?: number;    // Vị trí tùy chỉnh của mũi tên (px)
+
+  // Animation
+  animationConfig?: {
+    time?: number;       // Thời gian animation (giây). Default: 0.4
+    distance?: number;   // Khoảng cách trượt khi animate (px). Default: 12
+  };
+
+  // Hành vi
+  timerDestroy?: number;              // Delay (ms) trước khi ẩn khi chuột rời. Default: 0
+  zIndex?: number;                    // z-index của overlay
+  isAddContentToParentDocument?: boolean; // Render vào parent document (dùng trong iframe)
+  scrollOverlayOptions?: IScrollOverlayOptions; // Tùy chọn scroll cho overlay
 }
 ```
 
-## Styling
+### `TYPE_POPOVER_MODE` — Chế độ kích hoạt
+
+```typescript
+import { TYPE_POPOVER_MODE } from '@libs-ui/components-popover';
+
+type TYPE_POPOVER_MODE =
+  | 'hover'                                    // Hiển thị khi di chuột vào (mặc định)
+  | 'click'                                    // Hiển thị khi click vào, không tự đóng
+  | 'click-toggle'                             // Click để mở, click lần nữa để đóng
+  | 'click_open_and_click_panel_content_hidden'; // Click để mở, click vào nội dung overlay để đóng
+```
+
+### `TYPE_POPOVER_DIRECTION` — Hướng hiển thị
 
-### CSS Classes
+```typescript
+import { TYPE_POPOVER_DIRECTION } from '@libs-ui/components-popover';
 
-| Class                        | Description                         |
-| ---------------------------- | ----------------------------------- |
-| `.libs-ui-popover-container` | Lớp bao ngoài của nội dung popover. |
-| `.libs-ui-popover-arrow`     | Mũi tên chỉ hướng của popover.      |
+type TYPE_POPOVER_DIRECTION = 'top' | 'right' | 'bottom' | 'left';
+```
 
-## Công nghệ
+Khi hướng ưu tiên không đủ chỗ trong viewport, popover tự động thử theo thứ tự fallback:
+- `bottom` → `bottom`, `top`, `right`, `left`
+- `top` → `top`, `bottom`, `right`, `left`
+- `right` → `right`, `left`, `bottom`, `top`
+- `left` → `left`, `right`, `bottom`, `top`
 
-| Technology      | Version | Purpose            |
-| --------------- | ------- | ------------------ |
-| Angular         | 18+     | Framework          |
-| CDK Overlay     | 18+     | Positioning engine |
-| Angular Signals | -       | State management   |
-| TailwindCSS     | 3.x     | Styling            |
+### `TYPE_POPOVER_POSITION_MODE` — Căn chỉnh trục phụ
 
-## Demo
+```typescript
+import { TYPE_POPOVER_POSITION_MODE } from '@libs-ui/components-popover';
 
-```bash
-npx nx serve core-ui
+type TYPE_POPOVER_POSITION_MODE = 'start' | 'center' | 'end';
+// 'start'  → Căn về phía bắt đầu của phần tử gốc (trái khi direction là top/bottom)
+// 'center' → Căn giữa so với phần tử gốc (mặc định khi không chỉ định)
+// 'end'    → Căn về phía cuối của phần tử gốc (phải khi direction là top/bottom)
 ```
 
-Truy cập: `http://localhost:4200/popover`
+### `TYPE_POPOVER_EVENT` — Sự kiện
 
-## Unit Tests
+```typescript
+import { TYPE_POPOVER_EVENT } from '@libs-ui/components-popover';
+
+type TYPE_POPOVER_EVENT =
+  | 'show'               // Overlay vừa được hiển thị
+  | 'remove'             // Overlay vừa bị xóa
+  | 'click'              // Click vào host element
+  | 'mouseenter-element' // Chuột vào host element
+  | 'mouseleave-element' // Chuột rời khỏi host element
+  | 'mouseenter-content' // Chuột vào overlay content
+  | 'mouseleave-content'; // Chuột rời khỏi overlay content
+```
 
-```bash
-# Chạy tests
-npx nx test components-popover
+### `IPopoverFunctionControlEvent` — API điều khiển
+
+```typescript
+import { IPopoverFunctionControlEvent } from '@libs-ui/components-popover';
+
+interface IPopoverFunctionControlEvent {
+  showPopover: (elementRef?: HTMLElement) => Promise<void>;         // Hiển thị popover (tùy chọn gắn vào element khác)
+  removePopoverOverlay: () => Promise<void>;                        // Đóng và xóa overlay
+  updatePopoverOverlayPosition: () => Promise<void>;               // Tính toán lại vị trí overlay
+  updatePopoverOverlay: () => Promise<void>;                       // Cập nhật config và vị trí overlay
+  getRectContainer: () => Promise<IBoundingClientRect>;            // Lấy vị trí phần tử gốc
+  getRectContent: () => Promise<IBoundingClientRect>;              // Lấy vị trí overlay content
+}
+```
+
+### `IFlagMouse` — Trạng thái chuột
+
+```typescript
+import { IFlagMouse } from '@libs-ui/components-popover';
+
+interface IFlagMouse {
+  isMouseEnter: boolean;           // Chuột đang trong host element
+  isMouseEnterContent: boolean;    // Chuột đang trong overlay content
+  isContainerHasScroll?: boolean;  // Host element có scroll
+}
+```
+
+### `IPopover` — Interface tổng hợp
 
-# Coverage
-npx nx test components-popover --coverage
+```typescript
+import { IPopover } from '@libs-ui/components-popover';
+
+interface IPopover {
+  type?: TYPE_POPOVER_TYPE;
+  mode?: TYPE_POPOVER_MODE;
+  dataView?: string;
+  config?: IPopoverOverlay;
+  classInclude?: string;
+  ignoreShowPopover?: boolean;
+  ignoreHiddenPopoverContentWhenMouseLeave?: boolean;
+  elementRefCustom?: HTMLElement;
+  isAddContentToParentDocument?: boolean;
+  templateCustomContent?: TemplateRef<any>;
+}
 ```
 
-## License
+## Lưu ý quan trọng
+
+⚠️ **Một import cho cả hai cách dùng**: `LibsUiComponentsPopoverComponent` đăng ký cả selector dạng element (`libs_ui-components-popover`) lẫn attribute directive (`[LibsUiComponentsPopoverDirective]`). Chỉ cần import một lần vào `imports[]`.
+
+⚠️ **Không truyền cả `content` và `template` cùng lúc**: Nếu truyền cả hai, `content` sẽ bị bỏ qua. Chọn một trong hai cách truyền nội dung.
+
+⚠️ **`maxHeight: null` để tự động tính**: Khi đặt `maxHeight: null`, chiều cao overlay sẽ tự điều chỉnh dựa trên khoảng trống còn lại trong viewport (tính từ top của host element xuống đáy màn hình trừ 44px).
+
+⚠️ **Chế độ `hover` với `timerDestroy`**: Khi dùng nhiều popover lồng nhau (popover trong popover), sử dụng `[flagMouse]` và `(outChangStageFlagMouse)` để truyền trạng thái chuột giữa các popover, tránh đóng popover cha khi chuột đang trong popover con.
+
+⚠️ **Debug via URL query**: Có thể đặt thời gian delay trước khi ẩn popover qua URL query `?popover-timer-destroy=500` (đơn vị ms) — hữu ích khi debug bằng DevTools.
+
+⚠️ **Iframe support**: Khi component chạy trong iframe, dùng `[isAddContentToParentDocument]="true"` hoặc `config.isAddContentToParentDocument = true` để render overlay vào parent document và tránh bị cắt bởi `overflow: hidden`.
+
+## Demo
+
+```bash
+npx nx serve core-ui
+```
 
-MIT
+Truy cập: http://localhost:4500/components/popover

package/esm2022/interfaces/popover.interface.mjs

@@ -1,2 +1,2 @@
 export {};
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicG9wb3Zlci5pbnRlcmZhY2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi8uLi8uLi9saWJzLXVpL2NvbXBvbmVudHMvcG9wb3Zlci9zcmMvaW50ZXJmYWNlcy9wb3BvdmVyLmludGVyZmFjZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIiwic291cmNlc0NvbnRlbnQiOlsiLyogZXNsaW50LWRpc2FibGUgQHR5cGVzY3JpcHQtZXNsaW50L25vLWV4cGxpY2l0LWFueSAqL1xuaW1wb3J0IHsgVGVtcGxhdGVSZWYgfSBmcm9tICdAYW5ndWxhci9jb3JlJztcbmltcG9ydCB7IElQb3BvdmVyT3ZlcmxheSB9IGZyb20gJy4vb3ZlcmxheS5pbnRlcmZhY2UnO1xuaW1wb3J0IHsgVFlQRV9QT1BPVkVSX1RZUEUsIFRZUEVfUE9QT1ZFUl9NT0RFIH0gZnJvbSAnLi9wb3BvdmVyLnR5cGUnO1xuXG5leHBvcnQgaW50ZXJmYWNlIElQb3BvdmVyIHtcbiAgdHlwZT86IFRZUEVfUE9QT1ZFUl9UWVBFO1xuICBtb2RlPzogVFlQRV9QT1BPVkVSX01PREU7XG4gIGRhdGFWaWV3Pzogc3RyaW5nO1xuICBjb25maWc/OiBJUG9wb3Zlck92ZXJsYXkgfCB1bmRlZmluZWQ7XG4gIGNsYXNzSW5jbHVkZT86IHN0cmluZztcbiAgaWdub3JlU2hvd1BvcG92ZXI/OiBib29sZWFuO1xuICBpZ25vcmVIaWRkZW5Qb3BvdmVyQ29udGVudFdoZW5Nb3VzZUxlYXZlPzogYm9vbGVhbjtcbiAgZWxlbWVudFJlZkN1c3RvbT86IEhUTUxFbGVtZW50O1xuICBpc0FkZENvbnRlbnRUb1BhcmVudERvY3VtZW50PzogYm9vbGVhbjtcbiAgdGVtcGxhdGVDdXN0b21Db250ZW50PzogVGVtcGxhdGVSZWY8YW55PiB8IHVuZGVmaW5lZDtcbn1cbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicG9wb3Zlci5pbnRlcmZhY2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi8uLi8uLi9saWJzLXVpL2NvbXBvbmVudHMvcG9wb3Zlci9zcmMvaW50ZXJmYWNlcy9wb3BvdmVyLmludGVyZmFjZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIiwic291cmNlc0NvbnRlbnQiOlsiLyogZXNsaW50LWRpc2FibGUgQHR5cGVzY3JpcHQtZXNsaW50L25vLWV4cGxpY2l0LWFueSAqL1xuaW1wb3J0IHsgVGVtcGxhdGVSZWYgfSBmcm9tICdAYW5ndWxhci9jb3JlJztcbmltcG9ydCB7IElQb3BvdmVyT3ZlcmxheSB9IGZyb20gJy4vb3ZlcmxheS5pbnRlcmZhY2UnO1xuaW1wb3J0IHsgVFlQRV9QT1BPVkVSX1RZUEUsIFRZUEVfUE9QT1ZFUl9NT0RFIH0gZnJvbSAnLi9wb3BvdmVyLnR5cGUnO1xuXG5leHBvcnQgaW50ZXJmYWNlIElQb3BvdmVyIHtcbiAgdHlwZT86IFRZUEVfUE9QT1ZFUl9UWVBFO1xuICBtb2RlPzogVFlQRV9QT1BPVkVSX01PREU7XG4gIGRhdGFWaWV3Pzogc3RyaW5nO1xuICBjb25maWc/OiBJUG9wb3Zlck92ZXJsYXk7XG4gIGNsYXNzSW5jbHVkZT86IHN0cmluZztcbiAgaWdub3JlU2hvd1BvcG92ZXI/OiBib29sZWFuO1xuICBpZ25vcmVIaWRkZW5Qb3BvdmVyQ29udGVudFdoZW5Nb3VzZUxlYXZlPzogYm9vbGVhbjtcbiAgZWxlbWVudFJlZkN1c3RvbT86IEhUTUxFbGVtZW50O1xuICBpc0FkZENvbnRlbnRUb1BhcmVudERvY3VtZW50PzogYm9vbGVhbjtcbiAgdGVtcGxhdGVDdXN0b21Db250ZW50PzogVGVtcGxhdGVSZWY8YW55Pjtcbn1cbiJdfQ==