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

package/grid-layout.service.d.ts

@@ -24,6 +24,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 +36,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;
@@ -116,8 +118,20 @@ 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;
+    get totalColumns(): number;
     /** 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 +151,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 +186,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,4 @@
 export * from './grid-layout.service';
 export * from './canvas/grid-layout-canvas.component';
 export * from './interfaces/grid-layout.interface';
+export * from './defines/collision.define';

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

@@ -162,6 +162,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 +193,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-19",
+  "version": "0.2.357-21",
   "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-19",
-    "@libs-ui/utils": "0.2.357-19"
+    "@libs-ui/components-buttons-button": "0.2.357-21",
+    "@libs-ui/utils": "0.2.357-21"
   },
   "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;
     /**