@libs-ui/components-inputs-emoji 0.2.356-42 → 0.2.356-43

package/README.md

@@ -1,34 +1,33 @@
 # @libs-ui/components-inputs-emoji
 
-> Component chọn Emoji (Emoji Picker) tích hợp trong Popover với tính năng tìm kiếm và phân loại.
+> Component chọn Emoji (Emoji Picker) tích hợp trong Popover với tính năng tìm kiếm, phân loại và lazy loading.
 
 ## Giới thiệu
 
-`LibsUiComponentsEmojiComponent` cung cấp một giao diện chọn emoji trực quan, hỗ trợ đầy đủ các nhóm emoji tiêu chuẩn, tìm kiếm theo tên và tối ưu hóa hiệu năng bằng lazy loading khi cuộn danh sách.
+`LibsUiComponentsEmojiComponent` cung cấp giao diện chọn emoji trực quan ẩn trong một Popover, hỗ trợ duyệt emoji theo nhóm danh mục, tìm kiếm nhanh theo tên, và tối ưu hiệu năng bằng cơ chế lazy loading khi cuộn danh sách. Component phù hợp tích hợp vào mọi giao diện nhập liệu như chat, bình luận, hoặc soạn thảo văn bản.
 
-### Tính năng
+## Tính năng
 
-- ✅ Danh sách Emoji đầy đủ, phân loại theo nhóm
-- ✅ Tìm kiếm Emoji nhanh chóng
-- ✅ Tích hợp sẵn Popover thông minh
-- ✅ Lazy loading (scroll to load more) tối ưu hiệu năng
+- ✅ Danh sách Emoji đầy đủ, phân loại theo nhóm chuẩn Unicode
+- ✅ Tìm kiếm Emoji nhanh chóng theo tên (có xử lý unicode)
+- ✅ Tích hợp sẵn Popover với animation mượt mà
+- ✅ Lazy loading (scroll to load more) tối ưu hiệu năng với danh sách lớn
 - ✅ Hỗ trợ Custom Trigger qua `ng-content`
-- ✅ Tùy chỉnh linh hoạt kích thước và vị trí popup
+- ✅ Tùy chỉnh linh hoạt kích thước, vị trí và z-index của popup
+- ✅ Hỗ trợ điều khiển Popover từ bên ngoài qua `FunctionsControl` getter
+- ✅ Standalone component, tương thích Angular 17+ Signals & OnPush
 
 ## Khi nào sử dụng
 
-- Khi cần cho phép người dùng chèn cảm xúc (emoji) vào nội dung văn bản.
-- Phù hợp cho ứng dụng Chat, Comment, Social Media.
-- Khi cần một bộ chọn emoji chuyên nghiệp nhưng vẫn tiết kiệm diện tích giao diện.
+- Tích hợp tính năng chèn emoji trong các ứng dụng chat, bình luận, social media
+- Cần một bộ chọn emoji gọn nhẹ, tiết kiệm diện tích (ẩn trong popover cho đến khi cần)
+- Cần hiệu năng cao với danh sách emoji lớn (lazy loading tự động)
+- Muốn tùy chỉnh trigger button theo thiết kế riêng thay vì dùng icon mặc định
 
 ## Cài đặt
 
 ```bash
-# npm
 npm install @libs-ui/components-inputs-emoji
-
-# yarn
-yarn add @libs-ui/components-inputs-emoji
 ```
 
 ## Import
@@ -44,101 +43,256 @@ import { LibsUiComponentsEmojiComponent } from '@libs-ui/components-inputs-emoji
 export class YourComponent {}
 ```
 
-## Ví dụ
+## Ví dụ sử dụng
+
+### 1. Cơ bản — Icon mặc định làm trigger
+
+```typescript
+// component.ts
+import { Component, signal } from '@angular/core';
+import { LibsUiComponentsEmojiComponent } from '@libs-ui/components-inputs-emoji';
+
+@Component({
+  selector: 'app-chat-input',
+  standalone: true,
+  imports: [LibsUiComponentsEmojiComponent],
+  templateUrl: './chat-input.component.html',
+})
+export class ChatInputComponent {
+  protected selectedEmoji = signal('');
+
+  protected handlerSelectEmoji(emoji: string): void {
+    this.selectedEmoji.set(emoji);
+  }
+}
+```
+
+```html
+<!-- chat-input.component.html -->
+<div class="flex items-center gap-3">
+  <libs_ui-components-emoji (outEventEmoji)="handlerSelectEmoji($event)" />
+  <span class="text-gray-600">Emoji đã chọn: {{ selectedEmoji() || '(chưa chọn)' }}</span>
+</div>
+```
+
+### 2. Custom Trigger — Dùng nội dung bất kỳ làm trigger
+
+```typescript
+// component.ts
+import { Component, signal } from '@angular/core';
+import { LibsUiComponentsEmojiComponent } from '@libs-ui/components-inputs-emoji';
+
+@Component({
+  selector: 'app-comment-box',
+  standalone: true,
+  imports: [LibsUiComponentsEmojiComponent],
+  templateUrl: './comment-box.component.html',
+})
+export class CommentBoxComponent {
+  protected message = signal('');
+
+  protected handlerInsertEmoji(emoji: string): void {
+    this.message.update((current) => `${current}${emoji}`);
+  }
+}
+```
+
+```html
+<!-- comment-box.component.html -->
+<div class="flex items-center gap-2 border rounded-lg p-2">
+  <input
+    class="flex-1 outline-none text-sm"
+    [value]="message()"
+    placeholder="Nhập bình luận..." />
+
+  <libs_ui-components-emoji
+    [isNgContent]="true"
+    (outEventEmoji)="handlerInsertEmoji($event)">
+    <button class="px-3 py-1 bg-blue-500 text-white rounded text-sm hover:bg-blue-600">
+      😊 Emoji
+    </button>
+  </libs_ui-components-emoji>
+</div>
+```
+
+### 3. Tùy chỉnh kích thước Popup và vị trí
+
+```typescript
+// component.ts
+import { Component, signal } from '@angular/core';
+import { LibsUiComponentsEmojiComponent } from '@libs-ui/components-inputs-emoji';
 
-### Cơ bản
+@Component({
+  selector: 'app-editor-toolbar',
+  standalone: true,
+  imports: [LibsUiComponentsEmojiComponent],
+  templateUrl: './editor-toolbar.component.html',
+})
+export class EditorToolbarComponent {
+  protected selectedEmoji = signal('');
+
+  protected handlerPickEmoji(emoji: string): void {
+    this.selectedEmoji.set(emoji);
+  }
+}
+```
 
 ```html
-<libs_ui-components-emoji (outEventEmoji)="onSelect($event)" />
+<!-- editor-toolbar.component.html -->
+<libs_ui-components-emoji
+  classPopup="w-[400px] h-[350px]"
+  modePopoverPosition="center"
+  [zIndex]="1500"
+  (outEventEmoji)="handlerPickEmoji($event)" />
 ```
 
-### Custom Trigger
+### 4. Điều khiển Popover từ bên ngoài qua ViewChild
+
+```typescript
+// component.ts
+import { Component, viewChild } from '@angular/core';
+import { LibsUiComponentsEmojiComponent } from '@libs-ui/components-inputs-emoji';
+import { IPopoverFunctionControlEvent } from '@libs-ui/components-popover';
+
+@Component({
+  selector: 'app-controlled-emoji',
+  standalone: true,
+  imports: [LibsUiComponentsEmojiComponent],
+  templateUrl: './controlled-emoji.component.html',
+})
+export class ControlledEmojiComponent {
+  private readonly emojiRef = viewChild<LibsUiComponentsEmojiComponent>('emojiRef');
+  protected selectedEmoji = '';
+
+  protected handlerSelectEmoji(emoji: string): void {
+    this.selectedEmoji = emoji;
+    // Đóng popover sau khi chọn
+    this.emojiRef()?.FunctionsControl?.removePopoverOverlay();
+  }
+
+  openPicker(): void {
+    this.emojiRef()?.FunctionsControl?.showPopoverOverlay();
+  }
+}
+```
 
 ```html
+<!-- controlled-emoji.component.html -->
+<button (click)="openPicker()">Mở Emoji Picker</button>
 <libs_ui-components-emoji
-  [isNgContent]="true"
-  (outEventEmoji)="onSelect($event)">
-  <button>Chọn Emoji</button>
-</libs_ui-components-emoji>
+  #emojiRef
+  (outEventEmoji)="handlerSelectEmoji($event)" />
 ```
 
-## API
+## @Input()
+
+| Input | Type | Default | Mô tả | Ví dụ |
+|---|---|---|---|---|
+| `[classIconInclude]` | `string` | `'libs-ui-icon-add'` | CSS class cho icon trigger mặc định (khi không dùng ng-content) | `[classIconInclude]="'libs-ui-icon-smile'"` |
+| `[classInclude]` | `string` | `''` | CSS class bổ sung cho container của trigger button | `[classInclude]="'ml-2'"` |
+| `[classPopup]` | `string` | `'w-[290px] h-[245px]'` | CSS class cho container của popup chọn emoji, kiểm soát kích thước | `classPopup="w-[400px] h-[350px]"` |
+| `[configPopover]` | `IPopoverOverlay` | `defaultConfigPopover()` | Cấu hình đầy đủ cho Popover overlay (direction, position, animation,...) | `[configPopover]="myPopoverConfig"` |
+| `[isNgContent]` | `boolean` | `undefined` | Khi `true`, ẩn icon mặc định và dùng nội dung `ng-content` làm trigger | `[isNgContent]="true"` |
+| `[modePopoverPosition]` | `'start' \| 'center' \| 'end'` | `undefined` | Chế độ căn lề ngang của popup so với trigger | `modePopoverPosition="center"` |
+| `[zIndex]` | `number` | `0` | Z-index nền của popup. Content bên trong sẽ tự động được offset thêm `+5` | `[zIndex]="1500"` |
+| `[ignoreShowPopoverText]` | `boolean` | `undefined` | Ẩn tooltip text "Emoji" khi hover trigger | `[ignoreShowPopoverText]="true"` |
+
+## @Output()
 
-### libs_ui-components-emoji
+| Output | Type | Mô tả | Handler TS | Binding HTML |
+|---|---|---|---|---|
+| `(outEventEmoji)` | `string` | Emit ký tự emoji khi người dùng nhấn chọn một emoji trong picker | `handlerSelectEmoji(emoji: string): void { this.selectedEmoji.set(emoji); }` | `(outEventEmoji)="handlerSelectEmoji($event)"` |
+| `(outFunctionsControl)` | `IPopoverFunctionControlEvent` | Emit object chứa các hàm điều khiển Popover (`showPopoverOverlay`, `removePopoverOverlay`) | `handlerFunctionsControl(ctrl: IPopoverFunctionControlEvent): void { this.popoverCtrl = ctrl; }` | `(outFunctionsControl)="handlerFunctionsControl($event)"` |
+| `(outFlagMouse)` | `IFlagMouse` | Emit trạng thái chuột (hover) trên vùng popover | `handlerFlagMouse(flag: IFlagMouse): void { this.mouseFlag = flag; }` | `(outFlagMouse)="handlerFlagMouse($event)"` |
 
-#### Inputs
+## Methods (FunctionsControl)
 
-| Property                | Type                           | Default                  | Description                                  |
-| ----------------------- | ------------------------------ | ------------------------ | -------------------------------------------- |
-| `[classIconInclude]`    | `string`                       | `'libs-ui-icon-add'`     | CSS class cho icon trigger mặc định          |
-| `[classInclude]`        | `string`                       | `''`                     | CSS class bổ sung cho trigger container      |
-| `[classPopup]`          | `string`                       | `'w-[290px] h-[245px]'`  | CSS class cho container của popup chọn emoji |
-| `[configPopover]`       | `IPopoverOverlay`              | `defaultConfigPopover()` | Cấu hình overlay cho Popover                 |
-| `[isNgContent]`         | `boolean`                      | `false`                  | Sử dụng ng-content làm trigger thay vì icon  |
-| `[modePopoverPosition]` | `'start' \| 'center' \| 'end'` | `undefined`              | Chế độ căn lề cho Popover                    |
-| `[zIndex]`              | `number`                       | `0`                      | Giá trị Z-index nền của popup                |
+Truy cập qua `ViewChild` để điều khiển Popover theo chương trình:
 
-#### Outputs
+```typescript
+private readonly emojiRef = viewChild<LibsUiComponentsEmojiComponent>('emojiRef');
+
+// Mở picker
+this.emojiRef()?.FunctionsControl?.showPopoverOverlay();
+
+// Đóng picker
+this.emojiRef()?.FunctionsControl?.removePopoverOverlay();
+```
 
-| Property                | Type                           | Description                                         |
-| ----------------------- | ------------------------------ | --------------------------------------------------- |
-| `(outEventEmoji)`       | `string`                       | Emit khi người dùng chọn một emoji                  |
-| `(outFunctionsControl)` | `IPopoverFunctionControlEvent` | Emit các functions điều khiển Popover (show/remove) |
+| Getter | Return Type | Mô tả |
+|---|---|---|
+| `FunctionsControl` | `IPopoverFunctionControlEvent \| undefined` | Trả về object chứa hàm điều khiển Popover. Có giá trị sau khi Popover đã được khởi tạo. |
 
 ## Types & Interfaces
 
 ```typescript
-// Interface configure Popover
+import { IPopoverOverlay, IPopoverFunctionControlEvent, IFlagMouse } from '@libs-ui/components-popover';
+import { IEmoji, IGroupEmoji } from '@libs-ui/components-inputs-emoji';
+```
+
+```typescript
+/** Cấu hình Popover overlay */
 export interface IPopoverOverlay {
-  isAddContentToParentDocument?: boolean;
-  classInclude?: string;
-  widthByParent?: boolean;
-  width?: number;
-  minWidth?: number;
-  maxWidth?: number;
-  maxHeight?: number | null;
-  zIndex?: number;
   direction?: 'top' | 'right' | 'bottom' | 'left';
+  directionDistance?: number;
   position?: {
     mode: 'start' | 'center' | 'end';
     distance: number;
   };
-  // ... (see @libs-ui/components-popover for full list)
+  zIndex?: number;
+  maxWidth?: number;
+  maxHeight?: number | null;
+  width?: number;
+  minWidth?: number;
+  widthByParent?: boolean;
+  whiteTheme?: boolean;
+  ignoreArrow?: boolean;
+  classInclude?: string;
+  animationConfig?: object;
 }
 
+/** Các hàm điều khiển Popover (nhận qua outFunctionsControl hoặc FunctionsControl getter) */
 export interface IPopoverFunctionControlEvent {
   showPopoverOverlay: () => void;
   removePopoverOverlay: () => void;
 }
+
+/** Thông tin một Emoji */
+export interface IEmoji {
+  /** Ký tự emoji thực tế (vd: '😀') */
+  emoji: string;
+  /** Mô tả emoji bằng tiếng Anh (vd: 'grinning face') */
+  description: string;
+  /** Danh mục (vd: 'Smileys & Emotion') */
+  category: string;
+  display?: boolean;
+}
+
+/** Thông tin một nhóm Emoji */
+export interface IGroupEmoji {
+  /** Tên nhóm (vd: 'Smileys & Emotion') */
+  group_name: string;
+  /** Danh sách emoji trong nhóm */
+  emojis: Array<IEmoji>;
+  /** Ký tự đại diện cho nhóm */
+  iconGroup?: string;
+}
 ```
 
-## Công nghệ
+## Lưu ý quan trọng
 
-| Technology      | Version | Purpose          |
-| --------------- | ------- | ---------------- |
-| Angular         | 18+     | Framework        |
-| Angular Signals | -       | State management |
-| TailwindCSS     | 3.x     | Styling          |
-| OnPush          | -       | Change Detection |
+⚠️ **Z-index offset**: Z-index của nội dung bên trong popup luôn được offset thêm `+5` so với giá trị `[zIndex]` truyền vào. Khi dùng chung với modal hoặc overlay khác, hãy tính toán `zIndex` sao cho tránh bị che khuất.
 
-## Demo
+⚠️ **isNgContent**: Khi truyền `[isNgContent]="true"`, component sẽ ẩn hoàn toàn icon trigger mặc định và hiển thị phần tử con trong `ng-content`. Nếu `ng-content` rỗng, khu vực trigger sẽ không hiển thị gì.
 
-```bash
-npx nx serve core-ui
-```
+⚠️ **FunctionsControl timing**: Getter `FunctionsControl` trả về `undefined` cho đến khi sự kiện `(outFunctionsControl)` được emit lần đầu tiên (sau khi Popover khởi tạo). Hãy kiểm tra `?.` trước khi gọi.
 
-Truy cập: `http://localhost:4500/inputs/emoji`
+⚠️ **configPopover mutable**: `IPopoverOverlay` được xử lý theo dạng mutable object bên trong component. Không nên tái sử dụng cùng một object config cho nhiều instance Emoji Picker.
 
-## Unit Tests
+## Demo
 
 ```bash
-# Chạy tests
-npx nx test components-inputs-emoji
-
-# Coverage
-npx nx test components-inputs-emoji --coverage
+npx nx serve core-ui
 ```
 
-## License
-
-MIT
+Truy cập: http://localhost:4500/inputs/emoji

package/fesm2022/libs-ui-components-inputs-emoji.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { signal, input, output, viewChild, effect, untracked, ChangeDetectionStrategy, Component } from '@angular/core';
+import { signal, input, output, viewChild, effect, untracked, Component, ChangeDetectionStrategy } from '@angular/core';
 import { LibsUiComponentsInputsSearchComponent } from '@libs-ui/components-inputs-search';
 import { LibsUiComponentsPopoverComponent } from '@libs-ui/components-popover';
 import { LibsUiComponentsScrollOverlayDirective } from '@libs-ui/components-scroll-overlay';