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

package/grid-layout.service.d.ts

@@ -170,6 +170,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.
      *
@@ -250,7 +262,27 @@ export declare class LibsUiGridLayoutService {
         gridsterOptions: (depth: number, cb?: () => void) => GridsterConfig;
         attachNode: (node: T_gridLayout_node, depth: number, host: ViewContainerRef) => 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

@@ -73,6 +73,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 +157,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-22",
+  "version": "0.2.357-24",
   "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-22",
-    "@libs-ui/utils": "0.2.357-22"
+    "@libs-ui/components-buttons-button": "0.2.357-24",
+    "@libs-ui/utils": "0.2.357-24"
   },
   "sideEffects": false,
   "module": "fesm2022/libs-ui-services-grid-layout.mjs",