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

package/grid-layout.service.d.ts

@@ -1,4 +1,4 @@
-import { ViewContainerRef } from '@angular/core';
+import { TemplateRef, ViewContainerRef } from '@angular/core';
 import { GridsterConfig } from 'gridster18';
 import { T_gridLayout_changeEvent, T_gridLayout_newNode, T_gridLayout_config, T_gridLayout_node } from './interfaces/grid-layout.interface';
 import * as i0 from "@angular/core";
@@ -97,6 +97,10 @@ export declare class LibsUiGridLayoutService {
      *
      * @param host chỗ gắn RIÊNG của ô đó — mỗi khối một `ViewContainerRef`, dùng chung một cái thì
      *   mọi component bị dồn hết vào một ô.
+     * @param childCanvas khuôn mặt phẳng LỒNG của khối, chỉ có với khối container tự khai
+     *   `getComponentOutlet`. Component vỏ nhận nó qua input `childCanvas` và tự đặt vào giữa tiêu đề
+     *   với phần thân của mình. Không truyền xuống thì vỏ chiếm trọn chiều cao khối và đẩy toàn bộ thẻ
+     *   con ra ngoài vùng nhìn thấy.
      */
     private attachNode;
     /**
@@ -170,6 +174,18 @@ export declare class LibsUiGridLayoutService {
      * theo 24 cột còn màn hình chỉ có 12 — khối rơi ra ngoài mép phải mà không ai hiểu vì sao.
      */
     get totalColumns(): number;
+    /**
+     * Chiều cao một hàng lưới (pixel) dùng để tính khung xem trước lúc kéo thả.
+     *
+     * 🔴 Phải đọc từ `config.rowHeight` của nơi dùng. Trước đây `calculateDropGhost` đóng cứng 68, nên
+     * mặt phẳng khai hàng thấp thì khung xem trước cao gấp nhiều lần khối thật — nơi dùng phải ẩn khung
+     * của thư viện đi rồi tự vẽ lại.
+     */
+    get rowStepPx(): number;
+    /**
+     * Khe NHÌN THẤY giữa hai khối cấp gốc (px). `0` = không áp, giữ đúng hành vi cũ.
+     */
+    get visualGapPx(): number;
     /**
      * Đổi số cột / số hàng của một khối rồi vẽ lại.
      *
@@ -248,9 +264,29 @@ export declare class LibsUiGridLayoutService {
         resetZoom: (key?: string) => void;
         fitToScreen: (cW: number, sW?: number, pad?: number, key?: string) => number;
         gridsterOptions: (depth: number, cb?: () => void) => GridsterConfig;
-        attachNode: (node: T_gridLayout_node, depth: number, host: ViewContainerRef) => void;
+        attachNode: (node: T_gridLayout_node, depth: number, host: ViewContainerRef, childCanvas?: TemplateRef<unknown>) => void;
         detachNode: (nodeId: string) => void;
+        getNodeElement: (nodeId: string, scope?: ParentNode) => HTMLElement | undefined;
+        getNodeCanvasElement: (nodeId: string, scope?: ParentNode) => HTMLElement | undefined;
     };
+    /**
+     * Trả về vỏ DOM của một khối theo `id`.
+     *
+     * 🔴 Nơi dùng cần chạm vào DOM của khối (đo kích thước, gắn lớp phủ riêng) BẮT BUỘC đi qua đây.
+     * Trước khi có hàm này, nơi dùng phải tự viết `querySelector('.libs-ui-grid-layout-block-shell[...]')`
+     * — tức bám vào tên class NỘI BỘ của thư viện: đổi tên class là màn bên kia vỡ IM LẶNG, biên dịch
+     * vẫn xanh vì chuỗi selector không ai kiểm.
+     *
+     * `scope` giới hạn phạm vi tìm (mặc định cả tài liệu) — cần khi nhiều mặt phẳng cùng nằm trên màn.
+     */
+    getNodeElement(nodeId: string, scope?: ParentNode): HTMLElement | undefined;
+    /**
+     * Trả về mặt phẳng LỒNG nằm trong một khối container (khối có con), nếu có.
+     *
+     * Tách riêng khỏi `getNodeElement` vì nơi dùng thường cần chèn phần tử của mình vào TRƯỚC mặt phẳng
+     * lồng này (ví dụ hàng tiêu đề của khối ghép), nên phải cầm đúng nó chứ không phải cả vỏ.
+     */
+    getNodeCanvasElement(nodeId: string, scope?: ParentNode): HTMLElement | undefined;
     private applyInputs;
     static ɵfac: i0.ɵɵFactoryDeclaration<LibsUiGridLayoutService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<LibsUiGridLayoutService>;

package/interfaces/grid-layout.interface.d.ts

@@ -32,6 +32,21 @@ export type T_gridLayout_node = {
      * ```ts
      * getComponentOutlet: (node) => from(import('./chart-card.component').then((c) => c.ChartCardComponent))
      * ```
+     *
+     * 🔴 Khai cho khối CÓ CON (container) là khai VỎ của khối ghép — hàng tiêu đề, nút thu gọn, nền.
+     * Vỏ KHÔNG thay thế mặt phẳng lồng bên trong: thư viện truyền mặt phẳng đó xuống component vỏ qua
+     * input `childCanvas: TemplateRef<unknown>`, và vỏ BẮT BUỘC vẽ nó ra bằng `ngTemplateOutlet`, nếu
+     * không toàn bộ khối con biến mất khỏi màn.
+     *
+     * ```html
+     * <!-- trong component vỏ -->
+     * <div class="flex h-full flex-col">
+     *   <div class="shrink-0">{{ title() }}</div>
+     *   <div class="min-h-0 flex-1">
+     *     <ng-container [ngTemplateOutlet]="childCanvas()" />
+     *   </div>
+     * </div>
+     * ```
      */
     getComponentOutlet?: (node: T_gridLayout_node) => Observable<Type<unknown>>;
     /** dữ liệu riêng của nơi dùng — thư viện KHÔNG đọc, chuyển nguyên vào input `data` của component */
@@ -73,6 +88,15 @@ export type T_gridLayout_newNode = Omit<T_gridLayout_node, 'id' | 'x' | 'y'> & {
     id?: string;
     x?: number;
     y?: number;
+    /**
+     * Bật để GIỮ `x`/`y` truyền vào. Mặc định tắt: thư viện tự xếp khối xuống hàng trống kế tiếp.
+     *
+     * 🔴 Phải là cờ tường minh, KHÔNG suy ra từ việc có truyền `x`/`y` hay không: `0` vừa là toạ độ
+     * hợp lệ vừa là giá trị mọi hàm dựng node điền sẵn, nên đoán nhầm là khối mới đè lên khối cũ.
+     *
+     * Cờ này chỉ để điều khiển lúc thêm, không được lưu lại trong cây.
+     */
+    keepPosition?: boolean;
 };
 /**
  * Đi kèm sự kiện bấm nút THÊM trên một container.
@@ -148,6 +172,17 @@ export type T_gridLayout_config = {
     autoResizeNestedGrids?: boolean;
     /** khe giữa hai khối ở lưới CẤP TRANG, px. Mặc định 12 */
     margin?: number;
+    /**
+     * Khe NHÌN THẤY giữa hai khối cấp trang, px — phần vỏ khối thụt vào nửa khe mỗi cạnh.
+     *
+     * 🔴 Khác `margin`: `margin` là khe của Ô LƯỚI nên đổi nó là đổi luôn bước kéo và phép tính va
+     * chạm. Muốn thẻ trông thưa ra mà bước kéo giữ nguyên thì dùng `visualGap` — ô lưới không đổi,
+     * chỉ phần nhìn thấy co lại. Không khai thì không áp gì (giữ đúng hành vi cũ).
+     *
+     * Chỉ áp cho khối CẤP GỐC; khối con trong container giữ nguyên để không tách rời các dòng của
+     * cùng một thẻ.
+     */
+    visualGap?: number;
     /** khe giữa hai khối bên TRONG container, px. Mặc định 2 — khối con là dòng thông tin của cùng
      *  một card, khe rộng làm chúng trông như card rời nhau */
     nestedMargin?: number;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@libs-ui/services-grid-layout",
-  "version": "0.2.357-23",
+  "version": "0.2.357-25",
   "peerDependencies": {
     "@angular/core": "^18.2.0",
     "@angular/common": "^18.2.0",
     "gridster18": "npm:angular-gridster2@18.0.1",
     "rxjs": "~7.8.0",
-    "@libs-ui/components-buttons-button": "0.2.357-23",
-    "@libs-ui/utils": "0.2.357-23"
+    "@libs-ui/components-buttons-button": "0.2.357-25",
+    "@libs-ui/utils": "0.2.357-25"
   },
   "sideEffects": false,
   "module": "fesm2022/libs-ui-services-grid-layout.mjs",