@libs-ui/services-grid-layout 0.2.357-22 → 0.2.357-24

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

@@ -128,6 +128,11 @@ export declare class LibsUiGridLayoutCanvasComponent implements AfterViewInit, O
      */
     protected readonly toolbarContexts: import("@angular/core").Signal<T_gridLayout_toolbarContext[]>;
     protected readonly isNestedCanvas: import("@angular/core").Signal<boolean>;
+    /**
+     * Khe nhìn thấy giữa các khối CẤP GỐC. Mặt phẳng lồng trả 0 — khối con là các dòng của cùng một
+     * thẻ, tách chúng ra làm chúng trông như thẻ rời.
+     */
+    protected readonly visualGap: import("@angular/core").Signal<number>;
     /** trần lồng container — khối đã chạm trần thì không cho chuyển thành container */
     protected readonly maxContainerDepth: import("@angular/core").Signal<number>;
     /**

package/defines/collision.define.d.ts

@@ -27,7 +27,7 @@ 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;
+export declare const calculateDropGhost: (event: DragEvent, canvasContainer: HTMLElement, root: T_gridLayout_node, payload: T_gridLayout_externalDragPayload, totalCols?: number, rowStep?: 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. */

package/drag-controller.d.ts

@@ -28,7 +28,7 @@ export declare class LibsUiGridLayoutDragController {
      * 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;
+    onDragOver(event: DragEvent, container: HTMLElement | undefined, root: T_gridLayout_node | undefined, totalCols?: number, rowStep?: 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;
 }