@libs-ui/services-grid-layout 0.2.357-21 → 0.2.357-23

package/README.md

@@ -125,6 +125,10 @@ protected handlerAddInside(event: T_gridLayout_addEvent): void {
 | `outRemoveNode` | bấm nút xoá | `() => boolean` |
 | `outToggleType` | bấm gộp (khối đơn → container) hoặc tách | `() => boolean` |
 | `outAddBlockInside` | bấm ＋ trên container | `(item) => node \| undefined` |
+| `outDropNode` | vừa **thả** một thẻ kéo từ ngoài vào | — (khối đã chèn rồi) |
+| `outSelectNode` | bấm chọn một khối | — |
+| `outConfigNode` | bấm nút bánh răng trên khối | `() => true` |
+| `outZoomChange` | tỷ lệ thu phóng vừa đổi | — |
 
 `outChange` **không** bắn khi chính bạn gọi `addBlock`/`removeBlock`/`compact` — bạn đã biết mình vừa
 làm gì, khỏi phải chống dội.
@@ -152,7 +156,13 @@ làm gì, khỏi phải chống dội.
 | `compact()` | dồn khối lên, bỏ khoảng trống. Đệ quy vào container |
 | `findBlock(id)` · `findParentBlock(id)` | tra cây |
 | `exportLayout()` | cây hiện tại đã bỏ hàm, `cloneDeep` — gửi thẳng lên backend được |
-| `Root` · `IsEditMode` · `Version` | signal chỉ đọc |
+| `insertBlockWithCollision(item, col, row, parentId?)` | chèn vào ĐÚNG ô và đẩy khối va chạm xuống. `addBlock` thì tự tìm hàng trống kế tiếp |
+| `duplicateBlock(id, transformData?)` | nhân bản; `transformData` để bạn tự đổi dữ liệu của mình (thư viện không đoán trường nào là tiêu đề) |
+| `resizeBlock(id, { cols, rows })` | đổi kích thước bằng code; rộng quá mép phải thì tự dịch sang trái |
+| `setDragPayload(p)` · `clearDragPayload()` | báo cho canvas biết đang kéo thẻ gì từ palette ngoài vào |
+| `setZoom(v)` · `zoomIn()` · `zoomOut()` · `resetZoom()` · `fitToScreen(w)` | thu phóng |
+| `Root` · `IsEditMode` · `Version` · `Zoom` | signal chỉ đọc |
+| `totalColumns` | số cột thật của lưới cấp trang (mặc định 12) |
 
 Mọi hàm sửa cây **tự vẽ lại** — không phải gọi `refresh()` theo sau.
 
@@ -176,6 +186,111 @@ this.gridLayout.init({ data: UtilsCache.Get(KEY) ?? defaultLayout(), getComponen
 `exportLayout()` đã lược `getComponentOutlet` (hàm không tuần tự hoá được) nên `JSON.stringify` được
 ngay. Mở lại chỉ cần đưa `getComponentOutlet` vào `init` — cây không mang hàm.
 
+## Kéo thẻ từ palette bên ngoài vào
+
+Nơi dùng chỉ làm **hai việc ở thẻ palette**; canvas lo phần còn lại.
+
+```ts
+protected handlerPaletteDragStart(event: DragEvent, item: T_paletteItem): void {
+  this.gridLayout.setDragPayload({
+    type: item.type,
+    title: item.label,    // chữ trên khung xem trước
+    cols: item.cols,      // thư viện đo khung xem trước theo hai số này
+    rows: item.rows,
+    // Khối THẬT sẽ tạo. `isInside` = con trỏ đang trong một khối ghép ⇒ thu cho vừa ruột
+    // container (lưới con luôn 12 cột).
+    resolveNode: (isInside: boolean) => ({
+      cols: isInside ? 12 : item.cols,
+      rows: isInside ? 4 : item.rows,
+      data: { ...buildBlockData(item), label: '' },   // nhãn TRỐNG — đánh số ở `outDropNode`
+    }),
+  });
+  event.dataTransfer?.setData('text/plain', item.label);   // thiếu dòng này Firefox không kéo được
+}
+
+protected handlerPaletteDragEnd(): void {
+  this.gridLayout.clearDragPayload();   // người dùng thả RA NGOÀI canvas thì thư viện không bắn gì
+}
+```
+
+```html
+<div draggable="true"
+  (dragstart)="handlerPaletteDragStart($event, item)"
+  (dragend)="handlerPaletteDragEnd()">…</div>
+
+<libs_ui-services-grid_layout-canvas (outDropNode)="handlerDropNode($event)" />
+```
+
+🔴 **CẤM tự viết `(dragover)` / `(drop)` trên canvas.** Canvas đã làm: vẽ khung xem trước bám ô lưới,
+bật ô li của container khi con trỏ đi vào trong rồi tắt đúng lúc, chèn khối qua
+`insertBlockWithCollision` và đẩy khối va chạm xuống.
+
+🔴 **`resolveNode` phải THUẦN.** Thư viện gọi nó ở **mỗi nhịp `dragover`** chỉ để ĐO khung xem trước.
+Cấm tăng bộ đếm, sinh id, gọi API bên trong — đánh số khối thì đánh ở `outDropNode`.
+
+🔴 **`outDropNode` không có `confirm()`** — lúc nó bắn thì khối đã chèn rồi. Chặn trước thì chặn ở
+`dragstart`; gỡ sau thì `removeBlock(event.node.id)`. `event.parentId` khác `undefined` ⇒ người dùng
+thả vào ruột một khối ghép.
+
+`LibsUiGridLayoutDragController` là lớp **tuỳ chọn** cho trường hợp bạn tự dựng bề mặt thả riêng
+ngoài canvas. Dùng canvas sẵn có thì không cần đụng tới.
+
+## Thu phóng và Stage
+
+```ts
+this.gridLayout.init({
+  getComponentOutlet,
+  data: layoutFromServer(),
+  enableZoom: true,
+  stageWidth: 1400,        // 12 cột chia trên con số NÀY, không phải bề rộng cửa sổ
+  stageMinHeight: 900,
+  zoomMin: 0.4,
+  zoomMax: 1.5,
+  storageKey: 'bao_cao_ban_hang_zoom',   // 🔴 RIÊNG từng màn
+  autoFitOnLoad: true,
+});
+```
+
+Bật `enableZoom` là canvas dựng một **stage** khổ cố định rồi phóng to/thu nhỏ cả stage — bố cục
+nhìn giống nhau trên mọi khổ màn. Không bật thì 12 cột chia theo bề rộng cửa sổ, mỗi máy một kích
+thước khối.
+
+🔴 **`storageKey` phải riêng từng màn** — dùng chung thì hai màn ghi đè tỷ lệ của nhau.
+
+Canvas có sẵn cụm nút thu phóng ở góc; muốn đặt nút chỗ khác thì `[showZoomDock]="false"` rồi gọi
+`zoomIn()` · `zoomOut()` · `resetZoom()` · `setZoom(v)` · `fitToScreen(width)`.
+
+## Input của canvas
+
+| Input | Mặc định | Việc |
+|---|---|---|
+| `[(selectedNodeId)]` | `undefined` | khối đang chọn — **hai chiều**, thư viện ghi id vào signal của bạn |
+| `[(zoom)]` | `undefined` | tỷ lệ thu phóng — **hai chiều** |
+| `[showGridLines]` | `false` | vẽ ô li của lưới (lúc KÉO thư viện tự bật rồi tự tắt) |
+| `[showZoomDock]` | `true` | cụm nút thu phóng ở góc canvas |
+| `[enableExternalDrop]` | `true` | cho thả thẻ kéo từ ngoài vào |
+| `[hiddenToolbar]` | `false` | ẩn hẳn bộ nút mặc định trên khối |
+| `[templateToolbar]` | `undefined` | tự vẽ thanh công cụ của khối |
+
+🔴 **`node` và `depth` là input NỘI BỘ** — thư viện tự truyền khi vẽ lưới con. Mặt phẳng gốc đọc cây
+từ service (đã đưa vào qua `init()`), truyền thêm là khai hai lần cùng một thứ.
+
+```html
+<libs_ui-services-grid_layout-canvas [templateToolbar]="toolbar" />
+
+<ng-template #toolbar let-node
+  let-isContainer="isContainer" let-canAddInside="canAddInside"
+  let-remove="remove" let-addInside="addInside" let-toggleType="toggleType">
+  @if (canAddInside) { <button (click)="addInside()">＋</button> }
+  <button (click)="toggleType()">{{ isContainer ? 'Tách' : 'Gộp' }}</button>
+  <button (click)="remove()">Xoá</button>
+</ng-template>
+```
+
+🔴 `templateToolbar` đổi **giao diện**, không đổi **luật**: ba hàm trong context chỉ phát đúng sự
+kiện (`outRemoveNode` · `outAddBlockInside` · `outToggleType`), y như bấm nút mặc định. Vẫn phải bắt
+sự kiện rồi gọi `event.confirm()`.
+
 ## Vì sao cấu hình gridster lại như vậy
 
 `defines/gridster-config.define.ts` giữ toàn bộ cấu hình đã vá. Mỗi dòng có dấu 🔴 tương ứng một lỗi

package/canvas/grid-layout-canvas.component.d.ts

@@ -152,6 +152,7 @@ export declare class LibsUiGridLayoutCanvasComponent implements AfterViewInit, O
         resetZoom: () => void;
         fitToScreen: () => void;
         setZoom: (val: number) => void;
+        scrollArea: () => HTMLElement | undefined;
     };
     protected handlerZoomIn(): void;
     protected handlerZoomOut(): void;

package/defines/collision.define.d.ts

@@ -1,4 +1,4 @@
-import { T_gridLayout_dropGhost, T_gridLayout_externalDragPayload, T_gridLayout_node } from '../interfaces/grid-layout.interface';
+import { T_gridLayout_dropGhost, T_gridLayout_externalDragPayload, T_gridLayout_newNode, T_gridLayout_node } from '../interfaces/grid-layout.interface';
 /**
  * Checks whether the rectangular region [x, x + cols) x [y, y + rows)
  * is completely vacant among existing items.
@@ -28,4 +28,29 @@ export declare const findHoveredGroup: (elements: Element[], canvasContainer: HT
  * Calculates snapped spatial coordinates and pixel dimensions for drop ghost preview box.
  */
 export declare const calculateDropGhost: (event: DragEvent, canvasContainer: HTMLElement, root: T_gridLayout_node, payload: T_gridLayout_externalDragPayload, totalCols?: number) => T_gridLayout_dropGhost | undefined;
+/** Tìm khối theo id trong cây, đi sâu vào mọi container. */
+export declare const findNodeRecursive: (root: T_gridLayout_node, id: string) => T_gridLayout_node | undefined;
+/** Tìm khối CHA trực tiếp của một khối, đi sâu vào mọi container. */
+export declare const findParentRecursive: (root: T_gridLayout_node, id: string) => T_gridLayout_node | undefined;
+/**
+ * Thả khối vào đúng ô mà ghost đang chỉ, đẩy các khối va chạm xuống dưới.
+ *
+ * Ghost đang nằm trong một container (`isInsideGroup`) thì thả vào ruột container đó; không tìm thấy
+ * container thì trả `false` chứ KHÔNG rơi về lưới gốc — thả nhầm cấp khó nhận ra hơn là không thả.
+ */
+export declare const dropNodeAtCoordinates: (root: T_gridLayout_node, ghost: T_gridLayout_dropGhost, newNode: T_gridLayout_newNode) => boolean;
+/** Khối có phải CONTAINER không — tức có khối con bên trong. */
+export declare const isContainerNode: (node: T_gridLayout_node) => boolean;
+/** Khối có nằm LỒNG bên trong một container không (không phải con trực tiếp của gốc). */
+export declare const isNodeNestedInside: (root: T_gridLayout_node | undefined, nodeId: string) => boolean;
+/**
+ * Có được đổi khối đơn ↔ container không.
+ *
+ * 🔴 Ba hàm cờ này PHẢI là nguồn duy nhất cho cả thanh công cụ của thư viện lẫn menu do nơi dùng tự
+ * dựng. Trước đây nơi dùng phải chép lại quy tắc để dựng menu trước lúc render, và hai bản lệch nhau
+ * mỗi khi thư viện đổi trần lồng cấp mà không có gì báo.
+ */
+export declare const canToggleTypeNode: (root: T_gridLayout_node | undefined, node: T_gridLayout_node) => boolean;
+/** Có được thêm khối vào BÊN TRONG khối này không. */
+export declare const canAddInsideNode: (root: T_gridLayout_node | undefined, node: T_gridLayout_node) => boolean;
 export {};

package/drag-controller.d.ts

@@ -0,0 +1,34 @@
+import { T_gridLayout_dropGhost, T_gridLayout_externalDragPayload, T_gridLayout_node } from './interfaces/grid-layout.interface';
+/**
+ * Giữ trạng thái một lượt kéo khối từ palette bên ngoài vào mặt phẳng.
+ *
+ * Việc nó lo: bật ô li của lưới đang được kéo tới (lưới gốc, và lưới của container khi con trỏ đi
+ * vào trong), tắt đúng lúc, và trả về ghost để nơi dùng vẽ khung xem trước.
+ *
+ * 🔴 Tự bật/tắt ô li bằng tay ở nơi dùng là chỗ rất dễ sót: kéo ra khỏi container rồi mà quên tắt
+ * thì ô li của nó nằm lại trên màn, kéo sang lưới khác lại chồng thêm một lớp nữa.
+ */
+export declare class LibsUiGridLayoutDragController {
+    private payload?;
+    private hoveredElement?;
+    private rootGridsterElement?;
+    /** Payload của khối đang được kéo; `undefined` khi không có lượt kéo nào. */
+    get ActivePayload(): T_gridLayout_externalDragPayload | undefined;
+    /** Gọi ở `dragstart` của thẻ trong palette. */
+    onDragStart(payload: T_gridLayout_externalDragPayload): void;
+    /** Gọi ở `dragend` — dọn sạch mọi ô li đang bật. */
+    onDragEnd(container?: HTMLElement): void;
+    /** Tắt ô li của container đang hover. */
+    cleanupHoveredGroup(): void;
+    /** Tắt ô li của lưới gốc, và quét sạch lớp còn sót trong khung chứa. */
+    cleanupRootGrid(container?: HTMLElement): void;
+    /** Tắt toàn bộ ô li đang bật. */
+    cleanupAll(container?: HTMLElement): void;
+    /**
+     * Gọi ở `dragover` của khung chứa mặt phẳng. Trả ghost để nơi dùng vẽ khung xem trước, đồng thời
+     * tự bật ô li của lưới đang được kéo tới.
+     */
+    onDragOver(event: DragEvent, container: HTMLElement | undefined, root: T_gridLayout_node | undefined, totalCols?: number): T_gridLayout_dropGhost | undefined;
+    /** Bật ô li của lưới CẤP TRANG trong suốt lượt kéo, tắt lưới cũ nếu khung chứa đã đổi. */
+    private showRootGrid;
+}