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

package/canvas/grid-layout-canvas.component.d.ts

@@ -1,5 +1,5 @@
-import { OnDestroy } from '@angular/core';
-import { T_gridLayout_actionEvent, T_gridLayout_addEvent, T_gridLayout_changeEvent, T_gridLayout_node } from '../interfaces/grid-layout.interface';
+import { AfterViewInit, OnDestroy, TemplateRef } from '@angular/core';
+import { T_gridLayout_actionEvent, T_gridLayout_addEvent, T_gridLayout_changeEvent, T_gridLayout_dropEvent, T_gridLayout_dropGhost, T_gridLayout_node, T_gridLayout_toolbarContext, T_gridLayout_zoomPreset } from '../interfaces/grid-layout.interface';
 import * as i0 from "@angular/core";
 /**
  * Mặt phẳng kéo thả. Đệ quy: khối có `children` thì ruột nó lại là một mặt phẳng nữa.
@@ -7,7 +7,7 @@ import * as i0 from "@angular/core";
  * Nơi dùng KHÔNG dựng component này trực tiếp cho từng khối — chỉ đặt MỘT thẻ ở gốc và truyền
  * `nodeComponentType` qua `LibsUiGridLayoutService.init()`. Thư viện tự gắn component cho mọi khối.
  */
-export declare class LibsUiGridLayoutCanvasComponent implements OnDestroy {
+export declare class LibsUiGridLayoutCanvasComponent implements AfterViewInit, OnDestroy {
     /**
      * @internal Chỉ mặt phẳng LỒNG dùng — thư viện tự truyền khi vẽ ruột container.
      *
@@ -17,6 +17,23 @@ export declare class LibsUiGridLayoutCanvasComponent implements OnDestroy {
     readonly node: import("@angular/core").InputSignal<T_gridLayout_node | undefined>;
     /** @internal Chỉ mặt phẳng LỒNG dùng — thư viện tự truyền. */
     readonly depth: import("@angular/core").InputSignal<number>;
+    /**
+     * Ẩn hẳn thanh công cụ mặc định (thêm-vào-trong · gộp/tách · xoá) của MỌI khối.
+     *
+     * Dùng khi sản phẩm gom các hành động đó vào chỗ khác — vd một nút ⋮ nằm trong chính nội dung
+     * khối. Ẩn rồi thì `outRemoveNode` · `outAddBlockInside` · `outToggleType` không còn nguồn phát
+     * từ thư viện; nơi dùng tự gọi `removeBlock` · `addBlock` · `toggleType` của service.
+     */
+    readonly hiddenToolbar: import("@angular/core").InputSignalWithTransform<boolean, boolean | undefined>;
+    /**
+     * Template tự vẽ thanh công cụ, thay cho bộ nút mặc định.
+     *
+     * Nhận context `{ $implicit: node, isContainer, canAddInside, canToggleType }` để nơi dùng vẽ đúng
+     * nút cho từng khối, rồi gọi ngược qua `outRemoveNode` · `outAddBlockInside` · `outToggleType`
+     * bằng chính các hàm trong context. Truyền cả `hiddenToolbar` và `templateToolbar` thì
+     * `hiddenToolbar` thắng — không vẽ gì.
+     */
+    readonly templateToolbar: import("@angular/core").InputSignal<TemplateRef<T_gridLayout_toolbarContext> | undefined>;
     /**
      * Bố cục vừa đổi do NGƯỜI DÙNG kéo hoặc đổi kích thước khối.
      *
@@ -36,12 +53,60 @@ export declare class LibsUiGridLayoutCanvasComponent implements OnDestroy {
     readonly outAddBlockInside: import("@angular/core").OutputEmitterRef<T_gridLayout_addEvent>;
     /** Người dùng bấm nút GỘP/TÁCH. Thư viện chưa làm gì — gọi `event.confirm()` để thực hiện. */
     readonly outToggleType: import("@angular/core").OutputEmitterRef<T_gridLayout_actionEvent>;
+    /** Bật tính năng thu phóng (zoom) canvas. Chỉ áp dụng cho canvas gốc (depth 0). */
+    readonly enableZoom: import("@angular/core").InputSignalWithTransform<boolean, boolean | undefined>;
+    /** Tỷ lệ thu phóng hiện tại (hỗ trợ two-way binding [(zoom)]="myZoom"). */
+    readonly zoom: import("@angular/core").ModelSignal<number | undefined>;
+    /** Giới hạn thu phóng tối thiểu. Mặc định 0.4 (40%). */
+    readonly zoomMin: import("@angular/core").InputSignal<number>;
+    /** Giới hạn thu phóng tối đa. Mặc định 1.5 (150%). */
+    readonly zoomMax: import("@angular/core").InputSignal<number>;
+    /** Bước nhảy thu phóng mỗi lần bấm +/- hoặc lăn chuột. Mặc định 0.05 (5%). */
+    readonly zoomStep: import("@angular/core").InputSignal<number>;
+    /** Chiều rộng chuẩn của canvas stage tính bằng px. Mặc định 1668. */
+    readonly stageWidth: import("@angular/core").InputSignal<number>;
+    /** Chiều cao tối thiểu của canvas stage tính bằng px. Mặc định 937. */
+    readonly stageMinHeight: import("@angular/core").InputSignal<number>;
+    /** Khóa lưu tỷ lệ thu phóng vào localStorage. Mặc định 'ocb_bi_canvas_zoom'. */
+    readonly storageKey: import("@angular/core").InputSignal<string | undefined>;
+    /** Hiển thị thanh dock điều khiển thu phóng nổi ở góc dưới phải. Mặc định true. */
+    readonly showZoomDock: import("@angular/core").InputSignalWithTransform<boolean, boolean | undefined>;
+    /** Tự động vừa màn hình khi tải trang lần đầu nếu khung nhìn nhỏ hơn stageWidth. Mặc định true. */
+    readonly autoFitOnLoad: import("@angular/core").InputSignalWithTransform<boolean, boolean | undefined>;
+    /** Phát ra khi tỷ lệ thu phóng thay đổi. */
+    readonly outZoomChange: import("@angular/core").OutputEmitterRef<number>;
+    /** Bật tính năng kéo thả thẻ từ bên ngoài vào canvas (mặc định true) */
+    readonly enableExternalDrop: import("@angular/core").InputSignalWithTransform<boolean, boolean | undefined>;
+    /** Luôn hiển thị đường kẻ lưới 24 cột */
+    readonly showGridLines: import("@angular/core").InputSignalWithTransform<boolean, boolean | undefined>;
+    /** Mã id của khối đang được chọn */
+    readonly selectedNodeId: import("@angular/core").ModelSignal<string | null | undefined>;
+    /** Phát ra khi thả một thẻ mới từ bên ngoài vào canvas */
+    readonly outDropNode: import("@angular/core").OutputEmitterRef<T_gridLayout_dropEvent>;
+    /** Phát ra khi người dùng click chọn một khối */
+    readonly outSelectNode: import("@angular/core").OutputEmitterRef<T_gridLayout_node>;
+    /** Phát ra khi người dùng bấm nút cấu hình trên thanh công cụ của khối */
+    readonly outConfigNode: import("@angular/core").OutputEmitterRef<T_gridLayout_actionEvent>;
     private readonly gridsterRef;
+    private readonly scrollAreaRef;
+    private readonly zoomDockRef;
     /** mỗi ô một chỗ gắn riêng — cùng thứ tự với `children()` */
     private readonly itemHosts;
+    /** Khung xem trước vị trí thả thẻ từ bên ngoài (snapped ghost preview) */
+    protected readonly dropGhost: import("@angular/core").WritableSignal<T_gridLayout_dropGhost | undefined>;
+    private activeHoveredEl?;
+    private rootGridsterEl?;
+    /** Menu chọn preset thu phóng đang mở hay đóng */
+    protected readonly isMenuOpen: import("@angular/core").WritableSignal<boolean>;
+    /** Các mốc thu phóng định sẵn */
+    protected readonly zoomPresets: Array<T_gridLayout_zoomPreset>;
     /** Sáu chấm của tay cầm kéo — chỉ để `@for` dựng đủ 6 thẻ, giá trị không dùng tới. */
     protected readonly dragBarDots: number[];
     private readonly service;
+    /** Chế độ thu phóng có đang hoạt động trên canvas này không (chỉ root canvas depth 0) */
+    protected readonly isZoomActive: import("@angular/core").Signal<boolean>;
+    protected readonly currentZoom: import("@angular/core").Signal<number>;
+    protected readonly zoomPercent: import("@angular/core").Signal<number>;
     /**
      * Node THẬT của mặt phẳng này.
      *
@@ -55,6 +120,13 @@ export declare class LibsUiGridLayoutCanvasComponent implements OnDestroy {
      */
     protected readonly currentNode: import("@angular/core").Signal<T_gridLayout_node>;
     protected readonly children: import("@angular/core").Signal<T_gridLayout_node[]>;
+    /**
+     * Bối cảnh cho `templateToolbar`, dựng sẵn theo từng khối.
+     *
+     * Dựng ở `computed` chứ không gọi hàm trên template: gọi hàm trong template chạy lại mỗi vòng
+     * dò thay đổi (rule `fe-coding-convention-templates` mục 6).
+     */
+    protected readonly toolbarContexts: import("@angular/core").Signal<T_gridLayout_toolbarContext[]>;
     protected readonly isNestedCanvas: import("@angular/core").Signal<boolean>;
     /** 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>;
@@ -70,11 +142,29 @@ export declare class LibsUiGridLayoutCanvasComponent implements OnDestroy {
     protected readonly isEditMode: import("@angular/core").Signal<boolean>;
     protected readonly gridOptions: import("@angular/core").Signal<import("angular-gridster2").GridsterConfig>;
     constructor();
+    ngAfterViewInit(): void;
     ngOnDestroy(): void;
     /** Vẽ lại lưới — gọi khi khung ngoài đổi kích thước hoặc cây vừa đổi diện rộng. */
     get FunctionControl(): {
         veLaiLuoi: () => void | undefined;
+        zoomIn: () => void;
+        zoomOut: () => void;
+        resetZoom: () => void;
+        fitToScreen: () => void;
+        setZoom: (val: number) => void;
+        scrollArea: () => HTMLElement | undefined;
     };
+    protected handlerZoomIn(): void;
+    protected handlerZoomOut(): void;
+    protected handlerResetZoom(): void;
+    protected handlerFitScreen(): void;
+    protected handlerToggleMenu(): void;
+    protected handlerSelectPreset(value: number): void;
+    protected isCurrentPreset(value: number): boolean;
+    private syncZoomOut;
+    protected handlerWheel(event: WheelEvent): void;
+    protected handlerDocumentKeyDown(event: KeyboardEvent): void;
+    protected handlerDocumentClick(event: MouseEvent): void;
     protected handlerTrackNode(_index: number, item: T_gridLayout_node): string;
     /**
      * 🔴 Chặn `mousedown` nổi lên lưới CHA khi thao tác trong lưới con.
@@ -94,6 +184,17 @@ export declare class LibsUiGridLayoutCanvasComponent implements OnDestroy {
     protected handlerRemove(event: Event, node: T_gridLayout_node): void;
     protected handlerAddInside(event: Event, node: T_gridLayout_node): void;
     protected handlerToggleType(event: Event, node: T_gridLayout_node): void;
+    /**
+     * Chặn cú bấm trong thanh công cụ nổi lên gridster.
+     *
+     * Chỉ `stopPropagation`, KHÔNG `preventDefault`: nút bên trong template của nơi dùng vẫn cần
+     * hành vi mặc định của mình (mở dropdown, focus…).
+     */
+    protected handlerStopEvent(event: Event): void;
+    /** Phát `outAddBlockInside` — dùng chung cho nút mặc định và `templateToolbar`. */
+    private emitAddInside;
+    /** Phát `outToggleType` — dùng chung cho nút mặc định và `templateToolbar`. */
+    private emitToggleType;
     /** khối này có phải container không (có khối con) */
     protected isContainer(item: T_gridLayout_node): boolean;
     /** container đã chạm trần lồng thì không cho thêm khối vào trong nữa */
@@ -102,6 +203,13 @@ export declare class LibsUiGridLayoutCanvasComponent implements OnDestroy {
     protected canToggleType(item: T_gridLayout_node): boolean;
     protected handlerBlockParentDrag(event: Event): void;
     protected handlerMouseDownTrongLuoi(event: Event): void;
+    protected handlerSelectNode(node: T_gridLayout_node, event?: MouseEvent): void;
+    protected handlerConfig(event: Event, node: T_gridLayout_node): void;
+    protected handlerDragOver(event: DragEvent): void;
+    protected handlerDragLeave(event: DragEvent): void;
+    protected handlerDrop(event: DragEvent): void;
+    private cleanupHoveredGroup;
+    private cleanupDragGrid;
     static ɵfac: i0.ɵɵFactoryDeclaration<LibsUiGridLayoutCanvasComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<LibsUiGridLayoutCanvasComponent, "libs_ui-services-grid_layout-canvas", never, { "node": { "alias": "node"; "required": false; "isSignal": true; }; "depth": { "alias": "depth"; "required": false; "isSignal": true; }; }, { "outChange": "outChange"; "outRemoveNode": "outRemoveNode"; "outAddBlockInside": "outAddBlockInside"; "outToggleType": "outToggleType"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<LibsUiGridLayoutCanvasComponent, "libs_ui-services-grid_layout-canvas", never, { "node": { "alias": "node"; "required": false; "isSignal": true; }; "depth": { "alias": "depth"; "required": false; "isSignal": true; }; "hiddenToolbar": { "alias": "hiddenToolbar"; "required": false; "isSignal": true; }; "templateToolbar": { "alias": "templateToolbar"; "required": false; "isSignal": true; }; "enableZoom": { "alias": "enableZoom"; "required": false; "isSignal": true; }; "zoom": { "alias": "zoom"; "required": false; "isSignal": true; }; "zoomMin": { "alias": "zoomMin"; "required": false; "isSignal": true; }; "zoomMax": { "alias": "zoomMax"; "required": false; "isSignal": true; }; "zoomStep": { "alias": "zoomStep"; "required": false; "isSignal": true; }; "stageWidth": { "alias": "stageWidth"; "required": false; "isSignal": true; }; "stageMinHeight": { "alias": "stageMinHeight"; "required": false; "isSignal": true; }; "storageKey": { "alias": "storageKey"; "required": false; "isSignal": true; }; "showZoomDock": { "alias": "showZoomDock"; "required": false; "isSignal": true; }; "autoFitOnLoad": { "alias": "autoFitOnLoad"; "required": false; "isSignal": true; }; "enableExternalDrop": { "alias": "enableExternalDrop"; "required": false; "isSignal": true; }; "showGridLines": { "alias": "showGridLines"; "required": false; "isSignal": true; }; "selectedNodeId": { "alias": "selectedNodeId"; "required": false; "isSignal": true; }; }, { "outChange": "outChange"; "outRemoveNode": "outRemoveNode"; "outAddBlockInside": "outAddBlockInside"; "outToggleType": "outToggleType"; "zoom": "zoomChange"; "outZoomChange": "outZoomChange"; "selectedNodeId": "selectedNodeIdChange"; "outDropNode": "outDropNode"; "outSelectNode": "outSelectNode"; "outConfigNode": "outConfigNode"; }, never, never, true, never>;
 }

package/defines/collision.define.d.ts

@@ -0,0 +1,56 @@
+import { T_gridLayout_dropGhost, T_gridLayout_externalDragPayload, T_gridLayout_newNode, T_gridLayout_node } from '../interfaces/grid-layout.interface';
+/**
+ * Checks whether the rectangular region [x, x + cols) x [y, y + rows)
+ * is completely vacant among existing items.
+ */
+export declare const isRegionFree: (children: Array<T_gridLayout_node>, x: number, y: number, cols: number, rows: number, ignoredId?: string) => boolean;
+/**
+ * Computes optimal (col, row) inside a group container.
+ * Snaps flush to adjacent card right edge if slot is vacant.
+ */
+export declare const findSnapPositionInsideGroup: (children: Array<T_gridLayout_node>, rawCol: number, rawRow: number, innerCols: number, innerRows: number, totalCols?: number) => {
+    col: number;
+    row: number;
+};
+/**
+ * Resolves vertical collisions when inserting a new card at (newNode.x, newNode.y).
+ * Any existing card that horizontally overlaps and whose vertical span overlaps
+ * or is below the insertion point is pushed down so there is no overlap.
+ */
+export declare const resolveCollisionsAndInsert: (children: Array<T_gridLayout_node>, newNode: T_gridLayout_node) => void;
+export declare function parseDropPayload<T>(activePayload: T | undefined, dataTransfer: DataTransfer | null): T | undefined;
+interface I_hoveredGroup {
+    groupNode: T_gridLayout_node;
+    groupGridster: HTMLElement;
+}
+export declare const findHoveredGroup: (elements: Element[], canvasContainer: HTMLElement, root: T_gridLayout_node) => I_hoveredGroup | undefined;
+/**
+ * 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;
+/** 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. */
+export declare const findParentRecursive: (root: T_gridLayout_node, id: string) => T_gridLayout_node | undefined;
+/**
+ * Thả khối vào đúng ô mà ghost đang chỉ, đẩy các khối va chạm xuống dưới.
+ *
+ * Ghost đang nằm trong một container (`isInsideGroup`) thì thả vào ruột container đó; không tìm thấy
+ * container thì trả `false` chứ KHÔNG rơi về lưới gốc — thả nhầm cấp khó nhận ra hơn là không thả.
+ */
+export declare const dropNodeAtCoordinates: (root: T_gridLayout_node, ghost: T_gridLayout_dropGhost, newNode: T_gridLayout_newNode) => boolean;
+/** Khối có phải CONTAINER không — tức có khối con bên trong. */
+export declare const isContainerNode: (node: T_gridLayout_node) => boolean;
+/** Khối có nằm LỒNG bên trong một container không (không phải con trực tiếp của gốc). */
+export declare const isNodeNestedInside: (root: T_gridLayout_node | undefined, nodeId: string) => boolean;
+/**
+ * Có được đổi khối đơn ↔ container không.
+ *
+ * 🔴 Ba hàm cờ này PHẢI là nguồn duy nhất cho cả thanh công cụ của thư viện lẫn menu do nơi dùng tự
+ * dựng. Trước đây nơi dùng phải chép lại quy tắc để dựng menu trước lúc render, và hai bản lệch nhau
+ * mỗi khi thư viện đổi trần lồng cấp mà không có gì báo.
+ */
+export declare const canToggleTypeNode: (root: T_gridLayout_node | undefined, node: T_gridLayout_node) => boolean;
+/** Có được thêm khối vào BÊN TRONG khối này không. */
+export declare const canAddInsideNode: (root: T_gridLayout_node | undefined, node: T_gridLayout_node) => boolean;
+export {};

package/drag-controller.d.ts

@@ -0,0 +1,34 @@
+import { T_gridLayout_dropGhost, T_gridLayout_externalDragPayload, T_gridLayout_node } from './interfaces/grid-layout.interface';
+/**
+ * Giữ trạng thái một lượt kéo khối từ palette bên ngoài vào mặt phẳng.
+ *
+ * Việc nó lo: bật ô li của lưới đang được kéo tới (lưới gốc, và lưới của container khi con trỏ đi
+ * vào trong), tắt đúng lúc, và trả về ghost để nơi dùng vẽ khung xem trước.
+ *
+ * 🔴 Tự bật/tắt ô li bằng tay ở nơi dùng là chỗ rất dễ sót: kéo ra khỏi container rồi mà quên tắt
+ * thì ô li của nó nằm lại trên màn, kéo sang lưới khác lại chồng thêm một lớp nữa.
+ */
+export declare class LibsUiGridLayoutDragController {
+    private payload?;
+    private hoveredElement?;
+    private rootGridsterElement?;
+    /** Payload của khối đang được kéo; `undefined` khi không có lượt kéo nào. */
+    get ActivePayload(): T_gridLayout_externalDragPayload | undefined;
+    /** Gọi ở `dragstart` của thẻ trong palette. */
+    onDragStart(payload: T_gridLayout_externalDragPayload): void;
+    /** Gọi ở `dragend` — dọn sạch mọi ô li đang bật. */
+    onDragEnd(container?: HTMLElement): void;
+    /** Tắt ô li của container đang hover. */
+    cleanupHoveredGroup(): void;
+    /** Tắt ô li của lưới gốc, và quét sạch lớp còn sót trong khung chứa. */
+    cleanupRootGrid(container?: HTMLElement): void;
+    /** Tắt toàn bộ ô li đang bật. */
+    cleanupAll(container?: HTMLElement): void;
+    /**
+     * 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;
+    /** 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;
+}