@libs-ui/components-minimap 0.2.355-9 → 0.2.356-1

package/README.md

@@ -1,244 +1,138 @@
 # @libs-ui/components-minimap
 
-Directive tạo minimap (bản đồ thu nhỏ) để điều hướng nhanh trong nội dung có thể cuộn lớn. Giúp người dùng dễ dàng xem tổng quan và di chuyển đến vị trí mong muốn trong một vùng nội dung lớn.
+> Thêm bản đồ thu nhỏ (Minimap) cho các vùng chứa có nội dung lớn hoặc cuộn.
 
-## ✨ Tính năng
+## Giới thiệu
 
-• **Minimap tự động**: Tạo bản đồ thu nhỏ của element có thể cuộn
-• **Navigation tương tác**: Click và kéo thả để di chuyển viewport
-• **Tùy chỉnh style**: Cấu hình màu sắc, kích thước, vị trí minimap
-• **Responsive**: Tự động cập nhật khi nội dung thay đổi
-• **Performance tối ưu**: Sử dụng signal và RxJS cho hiệu suất cao
-• **Hỗ trợ scale**: Làm việc với element có transform scale
-• **Control functions**: API để show/hide/toggle minimap từ code
+`LibsUiComponentsMinimapDirective` là một standalone directive giúp tạo ra một trải nghiệm chuyển hướng trực quan cho người dùng trong các bảng vẽ (canvas), sơ đồ hoặc các vùng nội dung rộng lớn. Nó tự động theo dõi thay đổi trong DOM và đồng bộ hóa vị trí cuộn giữa nội dung chính và bản đồ thu nhỏ.
 
-## 📦 Cài đặt
+### Tính năng
 
-```bash
-npm install @libs-ui/components-minimap
-```
+- ✅ **Standalone Directive**: Dễ dàng tích hợp vào bất kỳ phần tử nào có thuộc tính cuộn.
+- ✅ **Đồng bộ hai chiều**: Cuộn nội dung chính cập nhật Minimap, kéo viewport trên Minimap cập nhật nội dung chính.
+- ✅ **Theo dõi thay đổi**: Sử dụng `MutationObserver` để tự động cập nhật hình ảnh trên Minimap khi nội dung thay đổi.
+- ✅ **Tùy biến cao**: Cho phép cấu hình vị trí, kích thước, màu sắc và z-index của cả Minimap và Viewport.
+- ✅ **Hỗ trợ Scale**: Khả năng nhận diện tỷ lệ phóng to/thu nhỏ của nội dung để hiển thị chính xác.
 
-<button onclick="navigator.clipboard.writeText('npm install @libs-ui/components-minimap')" class="copy-btn">📋 Sao chép</button>
+## Khi nào sử dụng
+
+- Khi có các vùng chứa nội dung lớn vượt quá kích thước màn hình (sơ đồ, bản đồ văn phòng, editor đồ họa).
+- Khi người dùng cần cái nhìn tổng quan về cấu trúc nội dung và khả năng di chuyển nhanh chóng đến các vùng cụ thể.
+- Thay thế hoặc hỗ trợ cho thanh cuộn truyền thống trên các giao diện phức tạp.
+
+## Cài đặt
 
 ```bash
+# npm
+npm install @libs-ui/components-minimap
+
+# yarn
 yarn add @libs-ui/components-minimap
 ```
 
-<button onclick="navigator.clipboard.writeText('yarn add @libs-ui/components-minimap')" class="copy-btn">📋 Sao chép</button>
-
-## 🚀 Sử dụng
-
-### Ví dụ cơ bản (Inline Template)
+## Import
 
 ```typescript
-import { Component } from '@angular/core';
 import { LibsUiComponentsMinimapDirective } from '@libs-ui/components-minimap';
 
 @Component({
-  selector: 'app-example',
   standalone: true,
   imports: [LibsUiComponentsMinimapDirective],
-  template: `
-    <div
-      LibsUiComponentsMinimapDirective
-      class="scrollable-content"
-      style="width: 500px; height: 300px; overflow: auto;">
-      <!-- Nội dung lớn cần minimap -->
-      <div style="width: 1500px; height: 1000px; background: linear-gradient(45deg, #ff6b6b, #4ecdc4);">
-        <h2>Nội dung rất lớn</h2>
-        <p>Cuộn để xem minimap hoạt động...</p>
-      </div>
-    </div>
-  `,
+  // ...
 })
-export class ExampleComponent {}
+export class YourComponent {}
 ```
 
-### Ví dụ với file HTML riêng
+## Ví dụ
 
-**Component:**
+### Cơ bản
 
-```typescript
-import { Component } from '@angular/core';
-import { LibsUiComponentsMinimapDirective, IMiniMapFunctionControl, IMiniMapStyleConfig } from '@libs-ui/components-minimap';
-
-@Component({
-  selector: 'app-minimap-demo',
-  standalone: true,
-  imports: [LibsUiComponentsMinimapDirective],
-  templateUrl: './minimap-demo.component.html',
-  styleUrls: ['./minimap-demo.component.scss'],
-})
-export class MinimapDemoComponent {
-  // Cấu hình style cho minimap container
-  minimapStyle: IMiniMapStyleConfig = {
-    width: 250,
-    height: 150,
-    top: 20,
-    right: 20,
-    background: '#f8f9fa',
-    border: '2px solid #007bff',
-    borderRadius: 8,
-    zIndex: 1500,
-  };
-
-  // Cấu hình style cho viewport rectangle
-  viewportStyle: IMiniMapStyleConfig = {
-    border: '2px solid #ff6b6b',
-    background: 'rgba(255, 107, 107, 0.1)',
-    borderRadius: 4,
-  };
-
-  minimapControls: IMiniMapFunctionControl | null = null;
-
-  // Nhận function controls từ directive
-  onMinimapReady(controls: IMiniMapFunctionControl) {
-    this.minimapControls = controls;
-  }
-
-  // Các method điều khiển minimap
-  showMinimap() {
-    this.minimapControls?.show();
-  }
-
-  hideMinimap() {
-    this.minimapControls?.hidden();
-  }
-
-  toggleMinimap() {
-    this.minimapControls?.toggle();
-  }
-}
+```html
+<div
+  class="w-full h-[500px] overflow-auto"
+  LibsUiComponentsMinimapDirective>
+  <!-- Nội dung lớn ở đây -->
+  <div class="w-[2000px] h-[2000px]">...</div>
+</div>
 ```
 
-**Template (minimap-demo.component.html):**
+### Với cấu hình Styles và Controls
 
 ```html
-<div class="demo-container">
-  <!-- Control buttons -->
-  <div class="controls mb-3">
-    <button
-      (click)="showMinimap()"
-      class="btn btn-success me-2">
-      Hiện Minimap
-    </button>
-    <button
-      (click)="hideMinimap()"
-      class="btn btn-warning me-2">
-      Ẩn Minimap
-    </button>
-    <button
-      (click)="toggleMinimap()"
-      class="btn btn-info">
-      Toggle Minimap
-    </button>
-  </div>
-
-  <!-- Scrollable content với minimap -->
-  <div
-    LibsUiComponentsMinimapDirective
-    [styleImageElement]="minimapStyle"
-    [styleRectangleElement]="viewportStyle"
-    [timerStartDrawMinimap]="500"
-    (outFunctionControls)="onMinimapReady($event)"
-    class="scrollable-area"
-    style="width: 600px; height: 400px; overflow: auto; border: 1px solid #ddd;">
-    <!-- Large content -->
-    <div
-      class="large-content"
-      style="width: 1200px; height: 800px; padding: 20px;">
-      <h1>Nội dung lớn với Minimap</h1>
-
-      <div
-        class="mo-minimap-flag-element-scale"
-        style="transform: scale(1.2);">
-        <!-- Element có scale để test tính năng scale detection -->
-        <div class="grid-content">
-          <!-- Tạo grid content để dễ nhận biết vị trí -->
-          <div
-            *ngFor="let row of [1,2,3,4,5,6,7,8,9,10]"
-            class="row"
-            style="display: flex; margin: 10px 0;">
-            <div
-              *ngFor="let col of [1,2,3,4,5,6,7,8,9,10]"
-              class="cell"
-              style="width: 80px; height: 60px; border: 1px solid #ccc; 
-                        margin: 2px; display: flex; align-items: center; 
-                        justify-content: center; background: #f0f0f0;">
-              {{row}}-{{col}}
-            </div>
-          </div>
-        </div>
-      </div>
-    </div>
-  </div>
+<div
+  class="scroll-container"
+  LibsUiComponentsMinimapDirective
+  [styleImageElement]="{ bottom: 20, right: 20, width: 200, height: 120 }"
+  [styleRectangleElement]="{ border: '2px solid #3b82f6' }"
+  (outFunctionControls)="controls = $event">
+  ...
 </div>
+
+<button (click)="controls.toggle()">Bật/Tắt Minimap</button>
 ```
 
-## 🛠️ Công nghệ sử dụng
+## API
 
-- **Angular 18+**: Framework chính
-- **RxJS**: Quản lý events và reactive programming
-- **TypeScript**: Ngôn ngữ phát triển
-- **Signals**: Quản lý state hiện đại của Angular
+### [LibsUiComponentsMinimapDirective]
 
-## 📖 API Reference
+#### Inputs
 
-### Inputs
+| Property                      | Type                  | Default                                | Description                                          |
+| ----------------------------- | --------------------- | -------------------------------------- | ---------------------------------------------------- |
+| `[elementScroll]`             | `HTMLElement`         | `Host Element`                         | Phần tử đích để theo dõi cuộn (nếu khác host).       |
+| `[styleImageElement]`         | `IMiniMapStyleConfig` | `undefined`                            | Cấu hình phong cách và vị trí cho khung Minimap.     |
+| `[styleRectangleElement]`     | `IMiniMapStyleConfig` | `undefined`                            | Cấu hình cho khung Viewport trên Minimap.            |
+| `[timerStartDrawMinimap]`     | `number`              | `250`                                  | Thời gian chờ (ms) trước khi bắt đầu vẽ Minimap.     |
+| `[classNameFlagElementScale]` | `string`              | `'libs-ui-minimap-flag-element-scale'` | Class name để xác định phần tử chứa scale transform. |
 
-| Tên                         | Kiểu                  | Mặc định                          | Mô tả                                                         |
-| --------------------------- | --------------------- | --------------------------------- | ------------------------------------------------------------- |
-| `classNameFlagElementScale` | `string`              | `'mo-minimap-flag-element-scale'` | Class name của element có scale transform để directive detect |
-| `timerStartDrawMinimap`     | `number`              | `250`                             | Thời gian delay (ms) trước khi bắt đầu vẽ minimap             |
-| `elementScroll`             | `HTMLElement`         | `undefined`                       | Element cuộn tùy chỉnh (mặc định dùng host element)           |
-| `styleRectangleElement`     | `IMiniMapStyleConfig` | `undefined`                       | Cấu hình style cho viewport rectangle                         |
-| `styleImageElement`         | `IMiniMapStyleConfig` | `undefined`                       | Cấu hình style cho minimap container                          |
+#### Outputs
 
-### Outputs
+| Property                | Type                                    | Description                                          |
+| ----------------------- | --------------------------------------- | ---------------------------------------------------- |
+| `(outFunctionControls)` | `EventEmitter<IMiniMapFunctionControl>` | Phát ra bộ điều khiển để điều khiển Minimap từ code. |
 
-| Tên                   | Kiểu                      | Mô tả                                            |
-| --------------------- | ------------------------- | ------------------------------------------------ |
-| `outFunctionControls` | `IMiniMapFunctionControl` | Emit object chứa các function để control minimap |
+#### Methods (via Controls)
 
-### Interfaces
+| Method     | Parameters | Description                     |
+| ---------- | ---------- | ------------------------------- |
+| `show()`   | `-`        | Hiển thị Minimap.               |
+| `hidden()` | `-`        | Ẩn Minimap.                     |
+| `toggle()` | `-`        | Chuyển đổi trạng thái hiển thị. |
 
-#### `IMiniMapStyleConfig`
+## Types & Interfaces
 
 ```typescript
-interface IMiniMapStyleConfig {
-  x?: number; // Vị trí x (không sử dụng)
-  y?: number; // Vị trí y (không sử dụng)
-  width?: number; // Chiều rộng minimap (px)
-  height?: number; // Chiều cao minimap (px)
-  zIndex?: number; // Z-index layer
-  border?: string; // CSS border
-  borderRadius?: number; // CSS border-radius (px)
-  background?: string; // CSS background
-  top?: number; // Vị trí top (px)
-  left?: number; // Vị trí left (px)
-  bottom?: number; // Vị trí bottom (px) - ưu tiên hơn top
-  right?: number; // Vị trí right (px) - ưu tiên hơn left
+export interface IMiniMapStyleConfig {
+  zIndex?: number;
+  border?: string;
+  borderRadius?: number;
+  background?: string;
+  top?: number;
+  left?: number;
+  bottom?: number;
+  right?: number;
+  width?: number;
+  height?: number;
+  x?: number;
+  y?: number;
 }
-```
-
-Cấu hình style cho minimap container hoặc viewport rectangle. Tất cả thuộc tính đều optional.
 
-#### `IMiniMapFunctionControl`
-
-```typescript
-interface IMiniMapFunctionControl {
-  show: () => void; // Hiển thị minimap
-  hidden: () => void; // Ẩn minimap
-  toggle: () => void; // Toggle hiển thị/ẩn minimap
+export interface IMiniMapFunctionControl {
+  show: () => void;
+  hidden: () => void;
+  toggle: () => void;
 }
 ```
 
-Object chứa các function để điều khiển minimap từ code. Nhận được qua output `outFunctionControls`.
+## Công nghệ
+
+| Technology       | Purpose                   |
+| ---------------- | ------------------------- |
+| Angular 18+      | Framework chính           |
+| Angular Signals  | Quản lý trạng thái nội bộ |
+| MutationObserver | Theo dõi thay đổi DOM     |
+| DOM Cloning      | Tạo hình ảnh thu nhỏ      |
 
-## 💡 Lưu ý
+## License
 
-- Directive tự động tạo minimap container và thêm vào `document.body`
-- Sử dụng class `mo-minimap-flag-element-scale` để đánh dấu element có scale transform
-- Minimap tự động cập nhật khi nội dung hoặc kích thước thay đổi
-- Viewport rectangle có thể click và kéo thả để điều hướng
-- Memory được quản lý tự động, tự cleanup khi component destroy
+MIT

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@libs-ui/components-minimap",
-  "version": "0.2.355-9",
+  "version": "0.2.356-1",
   "peerDependencies": {
     "@angular/core": ">=18.0.0",
-    "@libs-ui/interfaces-types": "0.2.355-9",
-    "@libs-ui/utils": "0.2.355-9",
+    "@libs-ui/interfaces-types": "0.2.356-1",
+    "@libs-ui/utils": "0.2.356-1",
     "rxjs": "~7.8.0"
   },
   "sideEffects": false,