@libs-ui/services-diagram-draw 0.2.356-42 → 0.2.356-43

package/README.md

@@ -1,9 +1,46 @@
 # @libs-ui/services-diagram-draw
 
-> **Version:** 0.2.356-3  
-> **Angular:** ^18.2.0
+> Bộ ba service Angular quản lý toàn bộ vòng đời diagram flow: tính toán tọa độ, render node động, vẽ SVG connector, quản lý kéo-thả và điều hướng luồng giữa các element.
 
-Service quản lý toàn bộ vòng đời của diagram flow: tính toán tọa độ element, render component động vào canvas, vẽ SVG connector, và quản lý drop zone kéo-thả thông minh.
+---
+
+## Giới thiệu
+
+`@libs-ui/services-diagram-draw` cung cấp ba service độc lập phối hợp với nhau để xây dựng diagram flow tương tác:
+
+- **`LibsUiDiagramDrawService`** — service trung tâm: tính tọa độ X/Y, render component node vào canvas, vẽ đường SVG, quản lý drop zone kéo-thả, hỗ trợ virtualization cho diagram lớn.
+- **`LibsUiDiagramDrawCanvasService`** — service quản lý cấu trúc dữ liệu diagram: thêm/xóa/thay thế element, xây dựng flat list, kiểm tra rule kết nối.
+- **`LibsUiDiagramDrawDirectionService`** — service quản lý điều hướng (connection line) giữa các element không liền kề: thêm/xóa/chỉnh sửa đường nối tự do.
+
+Hỗ trợ hai chế độ layout: **vertical** (dọc từ trên xuống, mặc định) và **horizontal** (ngang từ trái sang phải).
+
+---
+
+## Tính năng
+
+- Tính toán tọa độ tự động cho diagram dọc và ngang
+- Render Angular component động vào canvas (main node và nodeOtherConfig)
+- Vẽ SVG connector với cubic bezier tự động
+- Hiển thị mũi tên chỉ hướng (vertical: ▼, horizontal: ►) giữa các node
+- Render label trên nhánh (branch label) với màu sắc và class tùy chỉnh
+- Drop zone kéo-thả với indicator "+" tùy biến hoàn toàn
+- Virtualization — chỉ render node trong viewport, hỗ trợ diagram hàng trăm node
+- Quản lý thêm/xóa/thay thế/di chuyển element trong cấu trúc linked-list
+- Quản lý điều hướng tự do (next_other_id) và cleanup tự động khi xóa element
+- Build dữ liệu navigation line để kết hợp với `@libs-ui/components-draw-line`
+- Tự động tăng counter tên node khi thêm cùng loại (Email 1, Email 2, …)
+- Kiểm tra rule kết nối (elementCodeConnectableBefore) trước khi cho phép drop
+
+---
+
+## Khi nào sử dụng
+
+- Xây dựng giao diện thiết kế luồng tự động hóa (automation flow, journey builder)
+- Cần render động nhiều loại node component khác nhau trên cùng canvas
+- Diagram có cấu trúc phân nhánh (branching workflow) phức tạp
+- Cần tính năng kéo-thả từ sidebar vào luồng với validation rule
+- Diagram cần kết nối điều hướng tự do giữa các element không liền kề
+- Diagram lớn (>50 node) cần virtualization để tránh lag render
 
 ---
 
@@ -18,209 +55,581 @@ npm install @libs-ui/services-diagram-draw
 ## Import
 
 ```typescript
-import { LibsUiDiagramDrawService, canvasConfigReadonly, storeDataDefault } from '@libs-ui/services-diagram-draw';
+import {
+  LibsUiDiagramDrawService,
+  LibsUiDiagramDrawCanvasService,
+  LibsUiDiagramDrawDirectionService,
+  canvasConfigReadonly,
+  storeDataDefault,
+} from '@libs-ui/services-diagram-draw';
+
+import type {
+  IDiagramElement,
+  IDiagramElementBranch,
+  ICanvasConfig,
+  ICustomCanvasConfig,
+  IDiagramStoreData,
+  IDropZoneIndicatorStyle,
+  IRuleConnectable,
+  IHandlerFunction,
+  TDropZoneCanDropFn,
+  INavigationLineStyleConfig,
+} from '@libs-ui/services-diagram-draw';
 ```
 
+Ba service đều có `providedIn: 'root'` — inject trực tiếp bằng `inject()`, không cần khai báo trong `providers`.
+
 ---
 
-## Khởi tạo
+## Ví dụ sử dụng
+
+### Ví dụ 1 — Khởi tạo diagram cơ bản (vertical)
 
 ```typescript
-@Component({ ... })
+import { Component, AfterViewInit, ElementRef, ViewContainerRef, inject, viewChild } from '@angular/core';
+import {
+  LibsUiDiagramDrawService,
+  LibsUiDiagramDrawCanvasService,
+  storeDataDefault,
+  IDiagramElement,
+  IRuleConnectable,
+} from '@libs-ui/services-diagram-draw';
+import { MyNodeComponent } from './my-node.component';
+
+@Component({
+  selector: 'app-diagram',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    <div style="position: relative; overflow: auto; width: 100%; height: 100vh;">
+      <svg #svgContainer style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; pointer-events: none;">
+        <path style="fill: none; stroke: #9ca2ad; stroke-width: 1;"></path>
+      </svg>
+      <div #nodesContainer style="position: relative; width: 100%; height: 100%;"></div>
+      <ng-container #vcr></ng-container>
+    </div>
+  `,
+})
 export class DiagramComponent implements AfterViewInit {
-  @ViewChild('svgContainer') svgContainer!: ElementRef<SVGElement>;
-  @ViewChild('nodesContainer') nodesContainer!: ElementRef<HTMLDivElement>;
-  @ViewChild('vcr', { read: ViewContainerRef }) vcr!: ViewContainerRef;
+  private readonly svgContainer = viewChild<ElementRef<HTMLDivElement>>('svgContainer');
+  private readonly nodesContainer = viewChild<ElementRef<HTMLDivElement>>('nodesContainer');
+  private readonly vcr = viewChild('vcr', { read: ViewContainerRef });
 
   private readonly diagramService = inject(LibsUiDiagramDrawService);
+  private readonly canvasService = inject(LibsUiDiagramDrawCanvasService);
+
+  private readonly elements: IDiagramElement[] = [
+    { id: '1', code: 'EMAIL', name: 'Gửi Email 1', specific_width: 165, specific_height: 48, next_id: '2', pre_id: '' },
+    { id: '2', code: 'SMS',   name: 'Gửi SMS 1',   specific_width: 165, specific_height: 48, next_id: '3', pre_id: '1' },
+    { id: '3', code: 'EXIT',  element_type: 'EXIT', name: 'Kết thúc', specific_width: 165, specific_height: 48, pre_id: '2' },
+  ];
+
+  private readonly rules: IRuleConnectable[] = [
+    { elementCode: 'SMS',   elementCodeConnectableBefore: ['EMAIL', 'SMS'] },
+    { elementCode: 'EMAIL', elementCodeConnectableBefore: ['EMAIL', 'SMS'] },
+  ];
 
   ngAfterViewInit() {
-    // 1. Đăng ký config
-    this.diagramService.setConfig({
+    this.diagramService.setConfig = {
       storeDataDefine: { ...storeDataDefault },
-      svgContainer: this.svgContainer,
-      nodesContainer: this.nodesContainer,
-      viewContainerRef: this.vcr,
+      svgContainer: this.svgContainer(),
+      nodesContainer: this.nodesContainer(),
+      viewContainerRef: this.vcr(),
       nodeComponentType: MyNodeComponent,
-      nodeOtherConfigComponentType: MyWaitNodeComponent, // optional
-    });
+    };
 
-    // 2. Tính toán tọa độ
+    this.canvasService.loadElements(this.elements, { x: 200, y: 40 }, this.rules);
     this.diagramService.configXYElements(this.elements);
+    this.diagramService.renderNodes(this.elements);
+  }
+}
+```
+
+---
+
+### Ví dụ 2 — Diagram ngang (horizontal) với drop zone
+
+```typescript
+import { Component, AfterViewInit, ElementRef, ViewContainerRef, inject, viewChild } from '@angular/core';
+import {
+  LibsUiDiagramDrawService,
+  LibsUiDiagramDrawCanvasService,
+  storeDataDefault,
+  IDiagramElement,
+  IDiagramElementBranch,
+  IRuleConnectable,
+  TDropZoneCanDropFn,
+} from '@libs-ui/services-diagram-draw';
+import { MyNodeComponent } from './my-node.component';
+
+@Component({
+  selector: 'app-diagram-horizontal',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    <div style="position: relative; overflow: auto; width: 100%; height: 100vh;">
+      <svg #svgContainer style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; pointer-events: none;">
+        <path style="fill: none; stroke: #9ca2ad; stroke-width: 1;"></path>
+      </svg>
+      <div #nodesContainer style="position: relative; width: 100%; height: 100%;"></div>
+      <ng-container #vcr></ng-container>
+    </div>
+  `,
+})
+export class DiagramHorizontalComponent implements AfterViewInit {
+  private readonly svgContainer = viewChild<ElementRef<HTMLDivElement>>('svgContainer');
+  private readonly nodesContainer = viewChild<ElementRef<HTMLDivElement>>('nodesContainer');
+  private readonly vcr = viewChild('vcr', { read: ViewContainerRef });
+
+  private readonly diagramService = inject(LibsUiDiagramDrawService);
+  private readonly canvasService = inject(LibsUiDiagramDrawCanvasService);
 
-    // 3. Render nodes + SVG connector
+  private readonly elements: IDiagramElement[] = [
+    { id: '1', code: 'TRIGGER', name: 'Trigger 1', specific_width: 165, specific_height: 48, next_id: '2', pre_id: '' },
+    { id: '2', code: 'ACTION',  name: 'Action 1',  specific_width: 165, specific_height: 48, next_id: '3', pre_id: '1' },
+    { id: '3', code: 'EXIT',    element_type: 'EXIT', name: 'Kết thúc', specific_width: 165, specific_height: 48, pre_id: '2' },
+  ];
+
+  private readonly rules: IRuleConnectable[] = [
+    { elementCode: 'ACTION', elementCodeConnectableBefore: ['TRIGGER', 'ACTION'] },
+  ];
+
+  ngAfterViewInit() {
+    // Chuyển sang chế độ ngang
+    this.diagramService.orientation.set('horizontal');
+
+    this.diagramService.setConfig = {
+      storeDataDefine: { ...storeDataDefault },
+      svgContainer: this.svgContainer(),
+      nodesContainer: this.nodesContainer(),
+      viewContainerRef: this.vcr(),
+      nodeComponentType: MyNodeComponent,
+    };
+
+    this.canvasService.loadElements(this.elements, { x: 40, y: 200 }, this.rules);
+    this.diagramService.configXYElements(this.elements);
     this.diagramService.renderNodes(this.elements);
+    this.renderDropZones();
+  }
+
+  private renderDropZones() {
+    const canDropFn: TDropZoneCanDropFn = (_before, current, _after, _rules) => {
+      // Trả về true = ẨN drop zone, false = HIỂN THỊ
+      return current?.code === 'EXIT';
+    };
+
+    this.diagramService.renderDropZones(
+      this.canvasService.FlatElements,
+      (element: IDiagramElement, branch: IDiagramElementBranch | undefined, dragData: string) => {
+        const data: IDiagramElement = JSON.parse(dragData);
+        this.canvasService.addElement(element, branch, data);
+        this.diagramService.configXYElements(this.elements);
+        this.diagramService.renderNodes(this.elements);
+        this.renderDropZones();
+      },
+      canDropFn,
+      this.rules,
+    );
   }
 }
 ```
 
 ---
 
-## API
+### Ví dụ 3 — Diagram phân nhánh (WORKFLOW element)
 
-### Methods
+```typescript
+const elementsWithBranch: IDiagramElement[] = [
+  {
+    id: '1',
+    code: 'START',
+    name: 'Bắt đầu',
+    specific_width: 165,
+    specific_height: 48,
+    next_id: '2',
+    pre_id: '',
+  },
+  {
+    id: '2',
+    code: 'CONDITION',
+    element_type: 'WORKFLOW',
+    name: 'Điều kiện 1',
+    specific_width: 165,
+    specific_height: 48,
+    next_id: '5',
+    pre_id: '1',
+    branches: [
+      {
+        code: 'YES',
+        label: 'Đúng',
+        labelBgColor: '#dcfce7',
+        labelColor: '#15803d',
+        elements: [
+          { id: '3', code: 'EMAIL', name: 'Email 1', specific_width: 165, specific_height: 48, next_id: '', pre_id: '2' },
+        ],
+      },
+      {
+        code: 'NO',
+        label: 'Sai',
+        labelBgColor: '#fee2e2',
+        labelColor: '#dc2626',
+        elements: [
+          { id: '4', code: 'SMS', name: 'SMS 1', specific_width: 165, specific_height: 48, next_id: '', pre_id: '2' },
+        ],
+      },
+    ],
+  },
+  {
+    id: '5',
+    code: 'EXIT',
+    element_type: 'EXIT',
+    name: 'Kết thúc',
+    specific_width: 165,
+    specific_height: 48,
+    pre_id: '2',
+  },
+];
+```
 
-| Method                                                    | Parameters                             | Returns | Mô tả                                                                                               |
-| --------------------------------------------------------- | -------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
-| `set setConfig`                                           | `IConfig`                              | `void`  | Đăng ký config (ViewContainerRef, container refs, component types). Phải gọi trước mọi method khác. |
-| `set setConfigCanvas`                                     | `Partial<ICanvasConfig>`               | `void`  | Ghi đè các tham số canvas config (margin, kích thước, màu SVG, …).                                  |
-| `configXYElements(elements, updateSVG?, positionX?)`      | `IDiagramElement[], boolean?, number?` | `void`  | Tính toán tọa độ X/Y cho tất cả elements và cập nhật SVG path.                                      |
-| `renderNodes(elements)`                                   | `IDiagramElement[]`                    | `void`  | Clear nodes cũ, render component động, branch labels và arrow indicators.                           |
-| `clearNodes()`                                            | —                                      | `void`  | Destroy tất cả ComponentRef, xóa node-dynamic, branch-label, arrow-indicator khỏi DOM.              |
-| `renderDropZones(flatElements, onDrop, canDropFn, rules)` | Xem bên dưới                           | `void`  | Render drop zone "+" tại các vị trí cho phép kéo-thả.                                               |
-| `clearDropZones()`                                        | —                                      | `void`  | Xóa tất cả `.diagram-drop-zone` khỏi nodesContainer.                                                |
+---
 
-#### `renderDropZones` — chi tiết
+### Ví dụ 4 — Virtualization cho diagram lớn
+
+```typescript
+ngAfterViewInit() {
+  this.diagramService.setConfig = {
+    storeDataDefine: { ...storeDataDefault },
+    svgContainer: this.svgContainer(),
+    nodesContainer: this.nodesContainer(),
+    viewContainerRef: this.vcr(),
+    nodeComponentType: MyNodeComponent,
+    useVirtualizationTemplate: true,  // Bật virtualization
+  };
+
+  this.diagramService.configXYElements(this.elements);
+  this.diagramService.renderNodes(this.elements);
+
+  // Cập nhật viewport khi scroll
+  const container = this.nodesContainer()?.nativeElement.parentElement;
+  container?.addEventListener('scroll', () => {
+    this.diagramService.updateViewport({
+      x: container.scrollLeft,
+      y: container.scrollTop,
+      width: container.clientWidth,
+      height: container.clientHeight,
+    });
+  });
+}
+```
+
+---
+
+### Ví dụ 5 — Navigation line (kết nối tự do)
+
+```typescript
+import {
+  LibsUiDiagramDrawDirectionService,
+  LibsUiDiagramDrawCanvasService,
+  LibsUiDiagramDrawService,
+  INavigationLineStyleConfig,
+} from '@libs-ui/services-diagram-draw';
+
+// Trong component:
+private readonly directionService = inject(LibsUiDiagramDrawDirectionService);
+private readonly canvasService = inject(LibsUiDiagramDrawCanvasService);
+private readonly diagramService = inject(LibsUiDiagramDrawService);
+
+// Thêm điều hướng từ element tới target
+addDirection(sourceElement: IDiagramElement, targetId: string) {
+  const flatElements = this.canvasService.FlatElements;
+  this.directionService.addElementDirection(targetId, sourceElement, flatElements);
+}
+
+// Build dữ liệu navigation line để render qua draw-line directive
+buildNavigationLines() {
+  const styleConfig: INavigationLineStyleConfig = {
+    lineStyle: { color: '#6366f1', width: 1.5 },
+    arrowStyle: { color: '#6366f1', size: 8 },
+    endpointGap: 8,
+  };
+  const navData = this.diagramService.buildNavigationData(
+    this.canvasService.FlatElements,
+    styleConfig,
+  );
+  // Truyền navData vào drawLineFunctionControl.setData(navData)
+}
+```
+
+---
+
+## Methods — `LibsUiDiagramDrawService`
+
+| Method | Signature | Mô tả |
+|---|---|---|
+| `set setConfig` | `(config: ICustomCanvasConfig): void` | Đăng ký config (container refs, component types). Phải gọi trước mọi method khác. |
+| `set setConfigCanvas` | `(config: Partial<ICanvasConfig>): void` | Ghi đè tham số canvas config (margin, kích thước, màu SVG). |
+| `configXYElements` | `(elements: IDiagramElement[], updateSVG?: boolean, positionX?: number): void` | Tính toán tọa độ X/Y cho tất cả elements và cập nhật SVG path. |
+| `renderNodes` | `(elements: IDiagramElement[]): void` | Xóa node cũ, render component động, branch labels và arrow indicators. |
+| `clearNodes` | `(): void` | Destroy tất cả ComponentRef, xóa `.diagram-node-dynamic`, `.branch-label`, `.node-arrow-indicator` khỏi DOM. |
+| `renderDropZones` | `(flatElements, onDrop, canDropFn, rules): void` | Render drop zone "+" tại các vị trí cho phép kéo-thả. |
+| `clearDropZones` | `(): void` | Xóa tất cả `.diagram-drop-zone` khỏi nodesContainer. |
+| `updateViewport` | `(vp: { x, y, width, height }): void` | Cập nhật viewport để virtualization tính toán node hiển thị. Chỉ có hiệu lực khi `useVirtualizationTemplate: true`. |
+| `buildNavigationData` | `(flatElements: IDiagramElement[], styleConfig?: INavigationLineStyleConfig): IDrawLineDataInput[]` | Build dữ liệu navigation line từ `next_other_id` để render qua draw-line directive. |
+
+### Chi tiết `renderDropZones`
 
 ```typescript
 renderDropZones(
   flatElements: IDiagramElement[],
   onDrop: (element: IDiagramElement, branch: IDiagramElementBranch | undefined, dragData: string) => void,
-  canDropFn: TDropZoneCanDropFn,   // true = ẨN drop zone, false = HIỂN THỊ
-  ruleConnectableElements: IRuleConnectable[]
+  canDropFn: TDropZoneCanDropFn,
+  ruleConnectableElements: IRuleConnectable[],
 ): void
 ```
 
-### Exported Constants
+**Lưu ý:** `canDropFn` trả về `true` → **ẨN** drop zone; `false` → **HIỂN THỊ** drop zone (ngược với convention thông thường).
+
+---
 
-| Export                 | Type                               | Mô tả                                                                              |
-| ---------------------- | ---------------------------------- | ---------------------------------------------------------------------------------- |
-| `canvasConfigReadonly` | `Signal<ICanvasConfig>` (readonly) | Signal đọc config canvas global, dùng trong component mà không cần inject service. |
-| `storeDataDefault`     | `IDiagramStoreData`                | Giá trị mặc định cho `storeDataDefine`.                                            |
+## Methods — `LibsUiDiagramDrawCanvasService`
+
+| Method | Signature | Mô tả |
+|---|---|---|
+| `loadElements` | `(elements: IDiagramElement[], positionFirstNode: { x, y }, rules: IRuleConnectable[]): void` | Khởi tạo danh sách elements, đặt vị trí node đầu tiên, lưu rule kết nối. |
+| `addElement` | `(itemDrop, branchDrop, dataDrop, branchChoice?): void` | Thêm element vào sau `itemDrop`, tự động tạo EXIT node cho WORKFLOW. |
+| `removeOrChangeElement` | `(elementRemove, elementChange, branchChoose?): Promise<void>` | Xóa hoặc thay thế element, tự động thêm EXIT khi cần. |
+| `deleteChangeElementAndInsertBranchKeep` | `(elementRemove, elementChange, branchKeepElement, branchChoice?): Promise<void>` | Xóa element và giữ nguyên nhánh chỉ định. |
+| `addElementExitForAllElementPreviousWhenElementDelete` | `(elementsDelete: IDiagramElement[]): void` | Khi xóa hàng loạt element, tự động thêm EXIT cho các element đang trỏ vào vùng bị xóa. |
+| `checkRuleDragDrop` | `(before, current, after, rules): boolean` | Kiểm tra rule kết nối trước khi cho phép drop. |
+| `checkExistNameElement` | `(name: string, flatElements: IDiagramElement[]): boolean` | Kiểm tra tên element đã tồn tại chưa (case-insensitive). |
+| `get FlatElements` | `IDiagramElement[]` | Trả về flat list của tất cả element (bao gồm element trong branches). |
+| `set Elements` | `(elements: IDiagramElement[]): void` | Gán lại root elements array. |
+| `get Elements` | `IDiagramElement[]` | Lấy root elements array. |
+| `set HandlerFunction` | `(fn: IHandlerFunction): void` | Đăng ký callback tạo default config branches cho WORKFLOW element. |
+
+---
+
+## Methods — `LibsUiDiagramDrawDirectionService`
+
+| Method | Signature | Mô tả |
+|---|---|---|
+| `buildElementConnectTo` | `(element, flatElements, branch?, checkRule?): IDiagramElement[]` | Build danh sách element có thể kết nối tới. |
+| `addElementDirection` | `(targetId: string, element: IDiagramElement, flatElements: IDiagramElement[]): void` | Thêm điều hướng từ element tới target (cập nhật `next_other_id` và `pre_other_id`). |
+| `addBranchDirection` | `(targetId, element, branch, flatElements): void` | Thêm điều hướng từ branch của WORKFLOW element tới target. |
+| `editDirection` | `(flatElements, targetId, element, branch?): void` | Thay đổi điều hướng hiện tại sang target mới. |
+| `deleteElementsBehindElementConnectTo` | `(element, flatElements): void` | Xóa tất cả element phía sau khi element chuyển sang điều hướng. |
+| `deleteElementsBehindBranchConnectTo` | `(branch: IDiagramElementBranch): void` | Xóa tất cả element trong branch khi branch chuyển sang điều hướng. |
+| `set ElementDirection` | `(element: IDiagramElement | undefined): void` | Lưu element đang chọn điều hướng. |
+| `get ElementDirection` | `IDiagramElement | undefined` | Lấy element đang chọn điều hướng. |
+| `set BranchDirection` | `(branch: { branch, index } | undefined): void` | Lưu branch đang chọn điều hướng. |
+| `get OnViewDirection` | `Subject<{ id: string }>` | Observable phát khi cần highlight element đang được xem qua điều hướng. |
+
+---
+
+## Exported Constants
+
+| Export | Type | Mô tả |
+|---|---|---|
+| `canvasConfigReadonly` | `Signal<ICanvasConfig>` (readonly) | Signal đọc canvas config global — dùng trong component mà không cần inject service. |
+| `storeDataDefault` | `IDiagramStoreData` | Giá trị mặc định cho `storeDataDefine` trong `ICustomCanvasConfig`. |
 
 ---
 
 ## Canvas Config (`ICanvasConfig`)
 
-Tuỳ chỉnh qua `setConfigCanvas`:
-
-| Property                                         | Default      | Mô tả                                                   |
-| ------------------------------------------------ | ------------ | ------------------------------------------------------- |
-| `ELEMENT_WIDTH_DEFAULT_BRANCH_WHEN_NOT_ELEMENT`  | `60`         | Chiều rộng branch rỗng                                  |
-| `ELEMENT_MARGIN_DEFAULT`                         | `60`         | Margin dọc giữa các element                             |
-| `ELEMENT_MARGIN_DEFAULT_BRANCH`                  | `16`         | Margin element trong branch                             |
-| `ELEMENT_MARGIN_BETWEEN_BRANCH_DEFAULT`          | `60`         | Margin ngang giữa các branch                            |
-| `DEFAULT_BRANCH_WHEN_NO_ELEMENT`                 | `100`        | Chiều cao branch khi rỗng                               |
-| `ELEMENT_HEIGHT_CURVE`                           | `10`         | Độ cong SVG connector                                   |
-| `ELEMENT_SVG_STROKE_COLOR`                       | `'9ca2ad'`   | Màu đường kẻ SVG (không có `#`)                         |
-| `ELEMENT_SVG_STROKE_WIDTH`                       | `'1'`        | Độ dày đường kẻ SVG                                     |
-| `ELEMENT_MARGIN_DEFAULT_BRANCH_TO_ELEMENT_FIRST` | `78`         | Khoảng cách từ parent đến element đầu tiên trong branch |
-| `DISTANCE_TO_WAIT`                               | `30`         | Khoảng cách element chính → nodeOtherConfig             |
-| `WAIT_TO_ELEMENT`                                | `50`         | Khoảng cách nodeOtherConfig → element kế tiếp           |
-| `ELEMENT_WAIT_DEFAULT`                           | `28`         | Chiều cao mặc định nodeOtherConfig                      |
-| `DISTANCE_WAIT_TO_NEXT_LINE`                     | `4`          | Khoảng cách nodeOtherConfig → đường nối kế tiếp         |
-| `TYPE_ELEMENT_EXIT`                              | `'EXIT'`     | Loại element kết thúc (không có drop zone bên dưới)     |
-| `TYPE_ELEMENT_WORKFLOW`                          | `'WORKFLOW'` | Loại element có branches                                |
-| `WIDTH_ELEMENT_DEFAULT`                          | `165`        | Chiều rộng mặc định node                                |
-| `HEIGHT_ELEMENT_DEFAULT`                         | `48`         | Chiều cao mặc định node                                 |
-| `ADD_ICON_DIAMETER`                              | `24`         | Đường kính icon "+" drop zone                           |
+Tùy chỉnh qua `set setConfigCanvas`:
+
+| Property | Default | Mô tả |
+|---|---|---|
+| `ELEMENT_WIDTH_DEFAULT_BRANCH_WHEN_NOT_ELEMENT` | `60` | Chiều rộng branch rỗng (không có element) |
+| `ELEMENT_MARGIN_DEFAULT` | `60` | Khoảng cách dọc giữa các element (vertical) hoặc ngang (horizontal) |
+| `ELEMENT_MARGIN_DEFAULT_BRANCH` | `16` | Khoảng cách từ element có nhánh đến đường rẽ nhánh |
+| `ELEMENT_MARGIN_BETWEEN_BRANCH_DEFAULT` | `60` | Khoảng cách ngang giữa các branch (tối thiểu 32 để tương thích navigation line) |
+| `DEFAULT_BRANCH_WHEN_NO_ELEMENT` | `100` | Chiều cao/rộng branch khi không có element |
+| `ELEMENT_HEIGHT_CURVE` | `10` | Độ cong của SVG connector |
+| `ELEMENT_SVG_STROKE_COLOR` | `'9ca2ad'` | Màu đường kẻ SVG (không có ký tự `#` đứng trước) |
+| `ELEMENT_SVG_STROKE_WIDTH` | `'1'` | Độ dày đường kẻ SVG |
+| `ELEMENT_MARGIN_DEFAULT_BRANCH_TO_ELEMENT_FIRST` | `78` | Khoảng cách từ element cha đến element đầu tiên trong branch |
+| `DISTANCE_TO_WAIT` | `30` | Khoảng cách từ element chính đến `nodeOtherConfig` |
+| `WAIT_TO_ELEMENT` | `50` | Khoảng cách từ `nodeOtherConfig` đến element kế tiếp |
+| `ELEMENT_WAIT_DEFAULT` | `28` | Chiều cao mặc định của `nodeOtherConfig` |
+| `DISTANCE_WAIT_TO_NEXT_LINE` | `4` | Khoảng cách từ `nodeOtherConfig` đến đường nối tiếp theo |
+| `TYPE_ELEMENT_EXIT` | `'EXIT'` | Giá trị `code`/`element_type` cho element kết thúc (không có drop zone bên dưới) |
+| `TYPE_ELEMENT_WORKFLOW` | `'WORKFLOW'` | Giá trị `element_type` cho element có branches |
+| `WIDTH_ELEMENT_DEFAULT` | `165` | Chiều rộng mặc định node (dùng khi `specific_width` không được set) |
+| `HEIGHT_ELEMENT_DEFAULT` | `48` | Chiều cao mặc định node (dùng khi `specific_height` không được set) |
+| `ADD_ICON_DIAMETER` | `24` | Đường kính của icon "+" trong drop zone |
+
+Ví dụ tùy chỉnh:
+
+```typescript
+this.diagramService.setConfigCanvas = {
+  ELEMENT_MARGIN_DEFAULT: 80,
+  ELEMENT_SVG_STROKE_COLOR: '6366f1',
+  WIDTH_ELEMENT_DEFAULT: 200,
+  HEIGHT_ELEMENT_DEFAULT: 56,
+};
+```
 
 ---
 
-## Interfaces
+## Types & Interfaces
+
+```typescript
+import type {
+  IDiagramElement,
+  IDiagramElementBranch,
+  ICanvasConfig,
+  ICustomCanvasConfig,
+  IDiagramStoreData,
+  IDropZoneIndicatorStyle,
+  IRuleConnectable,
+  IHandlerFunction,
+  TDropZoneCanDropFn,
+  INavigationLineStyleConfig,
+} from '@libs-ui/services-diagram-draw';
+```
+
+### `IDiagramElement`
 
 ```typescript
 interface IDiagramElement {
-  code?: string; // Loại element (EXIT, WORKFLOW, …)
-  name?: string; // Tên hiển thị
-  id?: string; // Unique identifier
-  element_type?: string; // Type phân loại
-  branches?: IDiagramElementBranch[];
-  translateX?: number; // Tọa độ X (computed)
-  translateY?: number; // Tọa độ Y (computed)
-  specific_x?: number;
-  specific_y?: number;
-  specific_width?: number;
-  specific_height?: number;
-  attributeSvgD?: string; // SVG path string connector
-  nodeOtherConfig?: IDiagramElement; // Node phụ (wait/delay)
-  pre_id?: string;
-  next_id?: string;
-  disable?: boolean;
+  id?: string;                  // Unique identifier
+  code?: string;                // Loại element (VD: 'EMAIL', 'SMS', 'EXIT', 'CONDITION')
+  name?: string;                // Tên hiển thị
+  element_type?: string;        // 'WORKFLOW' cho element có nhánh, 'EXIT' cho kết thúc
+  branches?: IDiagramElementBranch[];   // Danh sách nhánh (chỉ có khi element_type = 'WORKFLOW')
+  next_id?: string;             // ID element kế tiếp trong luồng chính
+  pre_id?: string;              // ID element trước trong luồng chính
+  next_other_id?: string[];     // ID các element được điều hướng đến (kết nối tự do)
+  pre_other_id?: string[];      // ID các element điều hướng đến element này
+  nodeOtherConfig?: IDiagramElement;    // Node phụ (VD: wait node, delay config)
+  specific_x?: number;          // Vị trí X do người dùng/service set trước khi tính toán
+  specific_y?: number;          // Vị trí Y do người dùng/service set trước khi tính toán
+  specific_width?: number;      // Chiều rộng node (ghi đè WIDTH_ELEMENT_DEFAULT)
+  specific_height?: number;     // Chiều cao node (ghi đè HEIGHT_ELEMENT_DEFAULT)
+  translateX?: number;          // Tọa độ X cuối cùng sau khi tính toán (computed)
+  translateY?: number;          // Tọa độ Y cuối cùng sau khi tính toán (computed)
+  attributeSvgD?: string;       // SVG path string cho connector
+  subCodeOfElement?: string;    // Sub-type code dùng khi element có điều hướng
+  position_end?: number;        // Vị trí cuối của đường nối (computed)
+  disable?: boolean;            // Ẩn/vô hiệu hóa element
+  specific_counter_current_code?: number; // Counter đếm số lượng element cùng code
 }
+```
+
+### `IDiagramElementBranch`
 
+```typescript
 interface IDiagramElementBranch {
-  code?: string;
-  label?: string; // Label hiển thị trên nhánh
-  labelBgColor?: string; // Màu nền label
-  elements: IDiagramElement[];
-  onTheSide?: 'above' | 'under' | 'center';
-  specific_start_branch_x?: number;
-  specific_start_branch_y?: number;
-  nodeOtherConfig?: IDiagramElement;
-  isDirection?: boolean;
+  code?: string;                        // Định danh nhánh (VD: 'YES', 'NO')
+  label?: string;                       // Nhãn hiển thị trên nhánh (VD: 'Đúng', 'Sai')
+  labelBgColor?: string;                // Màu nền nhãn (VD: '#dcfce7')
+  labelColor?: string;                  // Màu chữ nhãn (VD: '#15803d')
+  labelClassName?: string;              // CSS class cho nhãn (mặc định: 'libs-ui-font-h7r')
+  elements: IDiagramElement[];          // Danh sách element trong nhánh
+  onTheSide?: 'above' | 'under' | 'center'; // Vị trí nhãn tương đối với nhánh
+  specific_start_branch_x?: number;    // Tọa độ X điểm đầu đường nhánh (computed)
+  specific_start_branch_y?: number;    // Tọa độ Y điểm đầu đường nhánh (computed)
+  next_other_id?: string[];            // ID các element được điều hướng từ nhánh này
+  isDirection?: boolean;               // Nhánh đang ở chế độ điều hướng
+  nodeOtherConfig?: IDiagramElement;   // Node phụ tại điểm rẽ nhánh
 }
+```
 
-interface IConfig {
-  storeDataDefine: IDiagramStoreData;
-  svgContainer?: ElementRef<HTMLDivElement>;
-  nodesContainer?: ElementRef<HTMLDivElement>;
-  viewContainerRef?: ViewContainerRef;
-  nodeComponentType?: Type<any>;
-  nodeOtherConfigComponentType?: Type<any>;
-  dropZoneStyle?: IDropZoneIndicatorStyle; // Tuỳ chỉnh indicator "+"
+### `ICustomCanvasConfig`
+
+```typescript
+interface ICustomCanvasConfig {
+  storeDataDefine: IDiagramStoreData;               // Lưu trữ tọa độ max — dùng storeDataDefault
+  svgContainer?: ElementRef<HTMLDivElement>;         // Ref đến SVG container để vẽ đường nối
+  nodesContainer?: ElementRef<HTMLDivElement>;       // Ref đến div chứa node component
+  viewContainerRef?: ViewContainerRef;              // ViewContainerRef để tạo component động
+  nodeComponentType?: Type<any>;                    // Component type cho main node
+  nodeOtherConfigComponentType?: Type<any>;         // Component type cho nodeOtherConfig
+  useVirtualizationTemplate?: boolean;              // Bật virtualization (mặc định: false)
+  dropZoneStyle?: IDropZoneIndicatorStyle;          // Tùy biến giao diện indicator "+"
 }
+```
+
+### `IRuleConnectable`
 
+```typescript
 interface IRuleConnectable {
-  elementCode: string;
-  elementCodeConnectableBefore: string[];
+  elementCode: string;                          // Code của element cần kiểm tra
+  elementCodeConnectableBefore: string[];       // Danh sách code được phép đứng trước
 }
-
-type TDropZoneCanDropFn = (before: IDiagramElement | undefined, current: IDiagramElement | undefined, after: IDiagramElement | undefined, rules: IRuleConnectable[]) => boolean;
 ```
 
----
+### `IHandlerFunction`
 
-## Tuỳ chỉnh indicator "+" (`IDropZoneIndicatorStyle`)
+```typescript
+interface IHandlerFunction {
+  getConfigDefaultBranches(code: string, dataDefault: IDiagramElement): IDiagramElement;
+}
+```
 
-Truyền vào `dropZoneStyle` của `IConfig` để kiểm soát giao diện nút `"+"` trong drop zone.
-Tất cả các field đều optional — giá trị nào không truyền sẽ dùng mặc định nội bộ của service.
+### `TDropZoneCanDropFn`
 
-### Thứ tự ưu tiên render
+```typescript
+type TDropZoneCanDropFn = (
+  beforeElementDrag: IDiagramElement | undefined,    // Element trước vị trí drop
+  currentElementDrag: IDiagramElement | undefined,   // Element tại vị trí drop
+  afterElementDrag: IDiagramElement | undefined,     // Element sau vị trí drop
+  ruleConnectableElements: IRuleConnectable[],
+) => boolean;  // true = ẨN drop zone, false = HIỂN THỊ
+```
 
-| Ưu tiên | Điều kiện                     | Kết quả                                                             |
-| ------- | ----------------------------- | ------------------------------------------------------------------- |
-| **1**   | `renderIndicator` được truyền | Toàn bộ HTML indicator do hàm này sinh ra                           |
-| **2**   | Không có `renderIndicator`    | SVG `"+"` tự sinh từ `backgroundColor`, `iconColor`, `borderRadius` |
+### `INavigationLineStyleConfig`
 
-| Ưu tiên | Điều kiện                          | Kết quả hover                                   |
-| ------- | ---------------------------------- | ----------------------------------------------- |
-| **1**   | `renderHoverIndicator` được truyền | Nội dung bên trong rectangle do hàm này sinh ra |
-| **2**   | Không có `renderHoverIndicator`    | Rectangle mở rộng trống (chỉ có nền + viền)     |
+```typescript
+interface INavigationLineStyleConfig {
+  lineStyle?: ILineStyle;           // Style đường kẻ (color, width, dash)
+  arrowStyle?: IArrowStyle;         // Style mũi tên (color, size)
+  endpointGap?: number;             // Khoảng cách từ cạnh node đến endpoint (mặc định: 8)
+  modeResolver?: (start: { x, y }, end: { x, y }) => TYPE_MODE; // Override chọn kiểu đường
+}
+```
 
-### Bảng thuộc tính
+---
 
-#### Indicator (trạng thái bình thường)
+## Tùy biến indicator "+" (`IDropZoneIndicatorStyle`)
 
-| Thuộc tính        | Kiểu                       | Mặc định    | Mô tả                                                                                        |
-| ----------------- | -------------------------- | ----------- | -------------------------------------------------------------------------------------------- |
-| `backgroundColor` | `string`                   | `'#3b82f6'` | Màu nền của indicator                                                                        |
-| `iconColor`       | `string`                   | `'#ffffff'` | Màu dấu `"+"` bên trong indicator                                                            |
-| `borderRadius`    | `string`                   | `'50%'`     | Bo góc indicator — `'50%'` cho tròn, `'6px'` cho vuông bo góc                                |
-| `opacity`         | `number`                   | `0.95`      | Độ mờ của indicator ở trạng thái bình thường                                                 |
-| `renderIndicator` | `(size: number) => string` | —           | **[Động]** Hàm trả về HTML tùy ý thay thế toàn bộ indicator. Ghi đè mọi field tĩnh bên trên. |
+Truyền vào `dropZoneStyle` của `ICustomCanvasConfig` để kiểm soát giao diện nút "+" trong drop zone.
 
-#### Hover / drag-enter (rectangle mở rộng)
+### Trạng thái bình thường
 
-| Thuộc tính             | Kiểu           | Mặc định                    | Mô tả                                                                                                          |
-| ---------------------- | -------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `hoverBackgroundColor` | `string`       | `'#eef4ff'`                 | Màu nền rectangle khi kéo vào vùng drop                                                                        |
-| `hoverBorderColor`     | `string`       | `'rgba(59, 130, 246, 0.7)'` | Màu đường viền rectangle                                                                                       |
-| `hoverBorderStyle`     | `string`       | `'dashed'`                  | Kiểu viền — `'dashed'` \| `'solid'` \| `'dotted'`                                                              |
-| `hoverBorderRadius`    | `number`       | `10`                        | Border-radius (px) của rectangle                                                                               |
-| `renderHoverIndicator` | `() => string` | —                           | **[Động]** Hàm trả về HTML inject vào bên trong rectangle. Nếu không truyền, rectangle chỉ hiển thị nền trống. |
+| Thuộc tính | Type | Mặc định | Mô tả |
+|---|---|---|---|
+| `backgroundColor` | `string` | `'#3b82f6'` | Màu nền của nút "+" |
+| `iconColor` | `string` | `'#ffffff'` | Màu dấu "+" bên trong |
+| `borderRadius` | `string` | `'50%'` | Bo góc — `'50%'` tròn, `'6px'` vuông |
+| `opacity` | `number` | `0.95` | Độ mờ ở trạng thái bình thường |
+| `renderIndicator` | `(size: number) => string` | — | Hàm trả về HTML tùy ý, ghi đè toàn bộ indicator |
 
-### Ví dụ
+### Trạng thái hover/drag-enter
 
-**Chỉ đổi màu và bo góc:**
+| Thuộc tính | Type | Mặc định | Mô tả |
+|---|---|---|---|
+| `hoverBackgroundColor` | `string` | `'#eef4ff'` | Màu nền vùng highlight khi kéo vào |
+| `hoverBorderColor` | `string` | `'rgba(59, 130, 246, 0.7)'` | Màu viền vùng highlight |
+| `hoverBorderStyle` | `string` | `'dashed'` | Kiểu viền: `'dashed'`, `'solid'`, `'dotted'` |
+| `hoverBorderRadius` | `number` | `10` | Border-radius (px) của vùng highlight |
+| `renderHoverIndicator` | `() => string` | — | Hàm trả về HTML inject vào bên trong vùng highlight |
+
+Ví dụ tùy biến màu sắc:
 
 ```typescript
 this.diagramService.setConfig = {
-  // ... các config khác
+  storeDataDefine: { ...storeDataDefault },
+  svgContainer: this.svgContainer(),
+  nodesContainer: this.nodesContainer(),
+  viewContainerRef: this.vcr(),
+  nodeComponentType: MyNodeComponent,
   dropZoneStyle: {
     backgroundColor: '#10b981',
     iconColor: '#ffffff',
-    borderRadius: '4px', // hình vuông bo góc thay vì tròn
+    borderRadius: '4px',
     opacity: 1,
     hoverBackgroundColor: '#f0fdf4',
     hoverBorderColor: 'rgba(16, 185, 129, 0.8)',
@@ -230,11 +639,15 @@ this.diagramService.setConfig = {
 };
 ```
 
-**Render indicator hoàn toàn tùy chỉnh:**
+Ví dụ render indicator hoàn toàn tùy chỉnh:
 
 ```typescript
 this.diagramService.setConfig = {
-  // ... các config khác
+  storeDataDefine: { ...storeDataDefault },
+  svgContainer: this.svgContainer(),
+  nodesContainer: this.nodesContainer(),
+  viewContainerRef: this.vcr(),
+  nodeComponentType: MyNodeComponent,
   dropZoneStyle: {
     renderIndicator: (size: number) => `
       <div style="
@@ -242,8 +655,8 @@ this.diagramService.setConfig = {
         background: #f59e0b; border-radius: 6px;
         display: flex; align-items: center; justify-content: center;
       ">
-        <svg viewBox="0 0 24 24" fill="white" width="14" height="14">
-          <path d="M12 5v14M5 12h14" stroke="white" stroke-width="2"/>
+        <svg viewBox="0 0 24 24" fill="none" width="14" height="14">
+          <path d="M12 5v14M5 12h14" stroke="white" stroke-width="2.5" stroke-linecap="round"/>
         </svg>
       </div>
     `,
@@ -252,9 +665,9 @@ this.diagramService.setConfig = {
         + Thêm vào đây
       </span>
     `,
-    hoverBackgroundColor: '#fafafa',
-    hoverBorderColor: 'rgba(139, 92, 246, 0.5)',
-    hoverBorderStyle: 'solid',
+    hoverBackgroundColor: '#fffbeb',
+    hoverBorderColor: 'rgba(245, 158, 11, 0.6)',
+    hoverBorderStyle: 'dashed',
     hoverBorderRadius: 12,
   },
 };
@@ -264,16 +677,28 @@ this.diagramService.setConfig = {
 
 ## Lưu ý quan trọng
 
-> ⚠️ Phải gọi `setConfig` trước khi dùng bất kỳ method nào khác.
+⚠️ **Thứ tự khởi tạo bắt buộc**: Phải gọi `set setConfig` trước mọi method khác của `LibsUiDiagramDrawService`.
+
+⚠️ **canvasConfig là signal global**: Thay đổi qua `set setConfigCanvas` sẽ ảnh hưởng đến mọi instance trong cùng app. Cần cẩn thận khi có nhiều diagram trên cùng trang.
 
-> ⚠️ `canvasConfig` là signal **global** — thay đổi sẽ ảnh hưởng đến mọi instance trong cùng app.
+⚠️ **`renderNodes()` tự gọi `clearNodes()` trước**: Không cần gọi thủ công trước khi render lại.
 
-> ⚠️ `renderNodes()` sẽ tự gọi `clearNodes()` trước khi render lại — không cần gọi thủ công trước.
+⚠️ **`canDropFn` logic ngược**: Trả về `true` → ẨN drop zone; `false` → HIỂN THỊ drop zone. Đây là thiết kế có chủ ý để hàm đóng vai trò "filter loại trừ".
 
-> ⚠️ `canDropFn` trả về `true` → **ẨN** drop zone; `false` → **HIỂN THỊ** drop zone.
+⚠️ **`ELEMENT_SVG_STROKE_COLOR` không có ký tự `#`**: Giá trị phải là mã hex thuần (VD: `'9ca2ad'`, không phải `'#9ca2ad'`).
+
+⚠️ **Virtualization yêu cầu scroll listener**: Khi bật `useVirtualizationTemplate: true`, cần tự lắng nghe sự kiện scroll của container và gọi `updateViewport()` để service cập nhật node hiển thị.
+
+⚠️ **`ELEMENT_MARGIN_BETWEEN_BRANCH_DEFAULT` tối thiểu 32**: Giá trị dưới 32px chưa tương thích với navigation line rendering.
+
+⚠️ **`loadElements` phải gọi trước `configXYElements`**: `LibsUiDiagramDrawCanvasService.loadElements()` khởi tạo vị trí node đầu tiên, cần được gọi trước khi service tính toán tọa độ.
 
 ---
 
 ## Demo
 
-Xem demo tại: `services/diagram-draw` trong core-ui app.
+```bash
+npx nx serve core-ui
+```
+
+Truy cập: `http://localhost:4500/services/diagram-draw`