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

package/grid-layout.service.d.ts

@@ -17,6 +17,13 @@ export declare class LibsUiGridLayoutService {
     private readonly treeService;
     /** Lượt tải component đang chờ, theo id khối — để huỷ khi khối bị gỡ giữa chừng. */
     private readonly pendingLoads;
+    /**
+     * Bộ theo dõi bề rộng của từng lưới LỒNG, để ngắt khi service bị huỷ.
+     *
+     * 🔴 Giữ tham chiếu là BẮT BUỘC: `ResizeObserver` không tự tắt theo vòng đời component. Không dọn
+     * thì mỗi lần nạp lại bố cục (đổi tab) lại chồng thêm một bộ, và chúng vẫn chạy trên DOM đã gỡ.
+     */
+    private readonly nestedResizeObservers;
     constructor();
     private config?;
     private readonly componentRefs;
@@ -24,6 +31,7 @@ export declare class LibsUiGridLayoutService {
     private readonly editMode;
     /** tăng mỗi lần cây đổi — component con đọc để biết phải tính lại */
     private readonly version;
+    private readonly zoomLevel;
     /**
      * Signal chỉ đọc để nơi dùng theo dõi.
      *
@@ -35,6 +43,7 @@ export declare class LibsUiGridLayoutService {
     readonly IsEditMode: import("@angular/core").Signal<boolean>;
     /** tăng mỗi lần cây hoặc cấu hình đổi */
     readonly Version: import("@angular/core").Signal<number>;
+    readonly Zoom: import("@angular/core").Signal<number>;
     /**
      * trần số cấp container lồng nhau — canvas đọc để biết có cho chuyển thành container không */
     private maxContainerDepth;
@@ -58,6 +67,30 @@ export declare class LibsUiGridLayoutService {
      * @param depth 0 = lưới cấp trang, ≥ 1 = lưới lồng trong container
      */
     private buildGridsterOptions;
+    /**
+     * Bắt lưới LỒNG đo lại NGAY khi khung chứa nó đổi bề rộng — dùng lúc người dùng kéo mép khối cha.
+     *
+     * Gridster có sẵn đường tự đo (`resize$`), nhưng luồng đó là `switchMap(() => timer(100))`: mỗi
+     * lần phát lại huỷ timer trước, mà kéo chuột bắn dày hơn 100ms nên timer không bao giờ tới đích.
+     * Đo được (11/09/2026): kéo mép nhóm thì lưới con co theo cha từng khung hình (234 → 384 px) còn
+     * THẺ con đứng im ở 106 px suốt cú kéo, chỉ nhảy đúng sau khi thả tay.
+     *
+     * Giữ CẢ HAI đường: `itemResizeCallback` bắn đồng bộ ngay khi gridster ghi bề rộng mới lên khối
+     * (sớm hơn `ResizeObserver` một khung hình) lo độ tức thì; `ResizeObserver` lo những lần khung đổi
+     * vì lý do khác — đổi zoom, thu gọn cột bên trái.
+     *
+     * Tắt bằng `config.autoResizeNestedGrids: false`.
+     */
+    private buildNestedResizeHooks;
+    /** Gọi `resize()` của một thẻ `<gridster>` qua chính instance mà nó tự gắn lên phần tử. */
+    private resizeGridsterElement;
+    /**
+     * Gắn instance lên chính phần tử `<gridster>` rồi theo dõi bề rộng của nó.
+     *
+     * Phải gắn ngược lên DOM vì `itemResizeCallback` của khối CHA chỉ cầm được `HTMLElement`, không có
+     * đường nào khác đi từ đó về instance của lưới lồng bên trong.
+     */
+    private registerNestedGrid;
     /**
      *
      * Gắn component của nơi dùng lên một khối.
@@ -116,8 +149,43 @@ export declare class LibsUiGridLayoutService {
      * @returns khối vừa tạo (kèm `id` vừa sinh), hoặc `undefined` khi không tìm thấy container.
      */
     addBlock(item: T_gridLayout_newNode, parentId?: string): T_gridLayout_node | undefined;
+    /**
+     * Thêm một khối tại toạ độ (col, row) cụ thể và tự động đẩy các khối va chạm xuống dưới.
+     */
+    insertBlockWithCollision(item: T_gridLayout_newNode, targetCol?: number, targetRow?: number, parentId?: string): T_gridLayout_node | undefined;
+    private readonly activeDragPayload;
+    /** Đặt payload khi bắt đầu kéo từ bên ngoài vào (ví dụ: palette, drawer) */
+    setDragPayload(payload: unknown): void;
+    /** Lấy payload đang kéo */
+    getDragPayload(): unknown;
+    /** Xoá payload khi kết thúc kéo */
+    clearDragPayload(): void;
     /** Xoá một khối. Xoá container là xoá cả ruột. Trả `false` khi không xoá được (vd khối gốc). */
     removeBlock(id: string): boolean;
+    /**
+     * Số cột thật của lưới cấp trang.
+     *
+     * 🔴 Mặc định phải TRÙNG `minCols/maxCols` của `gridLayoutRootConfig()`. Trước đây chỗ này trả 24
+     * trong khi lưới vẽ 12: nơi dùng không truyền `cols` thì va chạm, `toContainer` và `compact` tính
+     * 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;
+    /**
+     * Đổi số cột / số hàng của một khối rồi vẽ lại.
+     *
+     * Kéo `cols` rộng quá mép phải thì dịch khối sang trái cho vừa, thay vì để nó tràn ra ngoài lưới.
+     */
+    resizeBlock(id: string, size: {
+        cols?: number;
+        rows?: number;
+    }): boolean;
+    /**
+     * Nhân bản một khối — đặt kế bên phải nếu còn chỗ, không thì xuống dòng dưới.
+     *
+     * `transformData` để nơi dùng đổi phần dữ liệu riêng của mình (vd nối thêm "(Bản sao)" vào tiêu
+     * đề); thư viện không tự đoán trường nào là tiêu đề.
+     */
+    duplicateBlock(id: string, transformData?: (data: unknown) => unknown): T_gridLayout_node | undefined;
     /** Biến khối đơn thành CONTAINER — nội dung cũ thành khối con đầu tiên, không mất dữ liệu. */
     toContainer(id: string): boolean;
     /** Đưa CONTAINER về khối đơn — khối con được nâng lên cấp trên, không bị xoá. */
@@ -137,6 +205,31 @@ export declare class LibsUiGridLayoutService {
     findBlock(id: string): T_gridLayout_node | undefined;
     /** Tìm khối cha trực tiếp của một khối. */
     findParentBlock(id: string): T_gridLayout_node | undefined;
+    /**
+     * Đặt tỷ lệ thu phóng của canvas (kẹp giữa min và max).
+     *
+     * @param value Tỷ lệ (0.4 = 40%, 1.0 = 100%, 1.5 = 150%)
+     * @param persistKey Khóa localStorage để lưu lại (bỏ trống thì lấy từ config)
+     */
+    setZoom(value: number, persistKey?: string): void;
+    /** Phóng to thêm một bước (mặc định 0.05 tức 5%) */
+    zoomIn(step?: number, persistKey?: string): void;
+    /** Thu nhỏ bớt một bước (mặc định 0.05 tức 5%) */
+    zoomOut(step?: number, persistKey?: string): void;
+    /** Đặt lại tỷ lệ thu phóng gốc 100% (1.0) */
+    resetZoom(persistKey?: string): void;
+    /**
+     * Tự động tính toán và đặt tỷ lệ thu phóng để canvas vừa vặn với chiều rộng container.
+     *
+     * @param containerWidth Chiều rộng container đo được (px)
+     * @param stageWidth Chiều rộng chuẩn của canvas (mặc định 1668px)
+     * @param padding Khoảng cách lề hai bên (mặc định 48px)
+     * @param persistKey Khóa localStorage
+     * @returns Tỷ lệ thu phóng vừa tính
+     */
+    fitToScreen(containerWidth: number, stageWidth?: number, padding?: number, persistKey?: string): number;
+    /** Kiểm tra tính năng thu phóng có được cấu hình bật không */
+    isZoomConfigured(): boolean;
     /**
      * Cổng DUY NHẤT cho canvas của thư viện. Nơi dùng KHÔNG gọi tới đây.
      *
@@ -147,6 +240,13 @@ export declare class LibsUiGridLayoutService {
     get FunctionsControl(): {
         maxContainerDepth: () => number;
         containerPadding: () => number;
+        isZoomEnabled: () => boolean;
+        zoom: () => number;
+        setZoom: (v: number, key?: string) => void;
+        zoomIn: (step?: number, key?: string) => void;
+        zoomOut: (step?: number, key?: string) => void;
+        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;
         detachNode: (nodeId: string) => void;

package/index.d.ts

@@ -1,3 +1,5 @@
 export * from './grid-layout.service';
 export * from './canvas/grid-layout-canvas.component';
 export * from './interfaces/grid-layout.interface';
+export * from './defines/collision.define';
+export * from './drag-controller';

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

@@ -130,6 +130,22 @@ export type T_gridLayout_config = {
     cols?: number;
     /** chiều cao một hàng, px (chế độ lưới). Mặc định 56 */
     rowHeight?: number;
+    /**
+     * Số hàng TỐI THIỂU của lưới CẤP TRANG. Mặc định 2.
+     *
+     * Đặt lớn hơn khi muốn ô li phủ kín màn hình ngay cả lúc bố cục còn ít khối — lưới chỉ cao bằng
+     * khối cuối cùng thì phần dưới trống trơn, người dùng không biết còn thả được vào đâu.
+     */
+    minRows?: number;
+    /** Số hàng TỐI THIỂU của lưới bên TRONG container. Mặc định 1 */
+    nestedMinRows?: number;
+    /**
+     * Cho lưới LỒNG tự đo lại khi khung chứa nó đổi bề rộng. Mặc định BẬT.
+     *
+     * Tắt đi thì lúc kéo mép khối cha, thẻ con đứng im tới khi thả tay — chỉ tắt nếu nơi dùng tự lo
+     * việc đo lại.
+     */
+    autoResizeNestedGrids?: boolean;
     /** khe giữa hai khối ở lưới CẤP TRANG, px. Mặc định 12 */
     margin?: 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
@@ -162,6 +178,30 @@ export type T_gridLayout_config = {
     allowOverlap?: boolean;
     /** trần số cấp container lồng nhau. Mặc định 1 (container không chứa container) */
     maxContainerDepth?: number;
+    /** Bật tính năng thu phóng (zoom) canvas. Mặc định false */
+    enableZoom?: boolean;
+    /** Tỷ lệ thu phóng ban đầu. Mặc định 1 (100%) */
+    initialZoom?: number;
+    /** Giới hạn thu phóng tối thiểu. Mặc định 0.4 (40%) */
+    zoomMin?: number;
+    /** Giới hạn thu phóng tối đa. Mặc định 1.5 (150%) */
+    zoomMax?: number;
+    /** Bước nhảy mỗi lần tăng/giảm thu phóng. Mặc định 0.05 (5%) */
+    zoomStep?: number;
+    /** Chiều rộng chuẩn của canvas stage, px. Mặc định 1668 */
+    stageWidth?: number;
+    /** Chiều cao tối thiểu của canvas stage, px. Mặc định 937 */
+    stageMinHeight?: number;
+    /** Khóa lưu tỷ lệ thu phóng vào localStorage (vd 'ocb_bi_canvas_zoom') */
+    storageKey?: string;
+    /** Tự động vừa màn hình khi tải trang lần đầu nếu khung nhìn nhỏ hơn stage. Mặc định true */
+    autoFitOnLoad?: boolean;
+};
+/** Lựa chọn tỷ lệ thu phóng trên menu dropdown */
+export type T_gridLayout_zoomPreset = {
+    /** Khoá i18n, KHÔNG phải chữ hiển thị — template dịch qua `translate` pipe. */
+    label: string;
+    value: number;
 };
 /** Sự kiện thư viện bắn ra khi bố cục đổi */
 export type T_gridLayout_changeEvent = {
@@ -169,3 +209,71 @@ export type T_gridLayout_changeEvent = {
     /** khối vừa bị tác động; bỏ trống khi đổi diện rộng (sắp gọn, nạp lại) */
     nodeId?: string;
 };
+/**
+ * Bối cảnh truyền vào `templateToolbar` — template tự vẽ thanh công cụ thay bộ nút mặc định.
+ *
+ * ```html
+ * <ng-template #toolbar let-node let-ctx="ctx">
+ *   <libs_ui-components-buttons-button
+ *     [classIconLeft]="'libs-ui-icon-remove'"
+ *     (outClick)="ctx.remove()" />
+ * </ng-template>
+ * ```
+ */
+export type T_gridLayout_toolbarContext = {
+    /** khối đang vẽ — dùng `let-node` trong template */
+    $implicit: T_gridLayout_node;
+    /** khối này là container (có ruột) hay khối đơn */
+    isContainer: boolean;
+    /** còn thêm được khối vào trong không (chưa chạm trần lồng cấp) */
+    canAddInside: boolean;
+    /** đổi được giữa khối đơn ↔ khối ghép không */
+    canToggleType: boolean;
+    /** gọi để thư viện phát `outRemoveNode` như khi bấm nút xoá mặc định */
+    remove: () => void;
+    /** gọi để thư viện phát `outAddBlockInside` */
+    addInside: () => void;
+    /** gọi để thư viện phát `outToggleType` */
+    toggleType: () => void;
+};
+/** Khung xem trước (ghost preview) khi kéo thẻ từ bên ngoài vào canvas */
+export type T_gridLayout_dropGhost = {
+    col: number;
+    row: number;
+    cols: number;
+    rows: number;
+    pixelLeft: number;
+    pixelTop: number;
+    pixelWidth: number;
+    pixelHeight: number;
+    isInsideGroup: boolean;
+    targetParentId?: string;
+    groupTitle?: string;
+    cardTitle: string;
+    cardIconText?: string;
+    cardIconClass?: string;
+    hoveredGridster?: HTMLElement;
+};
+/** Sự kiện phát ra khi thả một thẻ mới từ bên ngoài vào canvas */
+export type T_gridLayout_dropEvent = {
+    node: T_gridLayout_node;
+    parentId?: string;
+    col: number;
+    row: number;
+    cols: number;
+    rows: number;
+    rawEvent: DragEvent;
+    payload?: unknown;
+};
+/** Dữ liệu của thẻ kéo từ bên ngoài vào canvas */
+export type T_gridLayout_externalDragPayload = {
+    kind?: string;
+    type?: string;
+    title?: string;
+    cols?: number;
+    rows?: number;
+    iconText?: string;
+    iconClass?: string;
+    data?: Record<string, unknown>;
+    [key: string]: unknown;
+};

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@libs-ui/services-grid-layout",
-  "version": "0.2.357-20",
+  "version": "0.2.357-22",
   "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-20",
-    "@libs-ui/utils": "0.2.357-20"
+    "@libs-ui/components-buttons-button": "0.2.357-22",
+    "@libs-ui/utils": "0.2.357-22"
   },
   "sideEffects": false,
   "module": "fesm2022/libs-ui-services-grid-layout.mjs",

package/tree.service.d.ts

@@ -17,6 +17,10 @@ export declare class LibsUiGridLayoutTreeService {
      * @returns khối vừa tạo (kèm `id` vừa sinh), hoặc `undefined` khi không tìm thấy container.
      */
     addChild(root: T_gridLayout_node, parentId: string, item: T_gridLayout_newNode): T_gridLayout_node | undefined;
+    /**
+     * Thêm khối vào vị trí (x, y) cụ thể và tự động đẩy các khối va chạm xuống dưới.
+     */
+    insertWithCollision(root: T_gridLayout_node, parentId: string | undefined, item: T_gridLayout_newNode, targetCol?: number, targetRow?: number): T_gridLayout_node | undefined;
     /** Xoá một khối khỏi cây. Không cho xoá gốc. */
     removeById(root: T_gridLayout_node, id: string): boolean;
     /**