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

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

@@ -1,4 +1,5 @@
 import { AfterViewInit, OnDestroy, TemplateRef } from '@angular/core';
+import { IScrollOverlayOptions } from '@libs-ui/components-scroll-overlay';
 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";
 /**
@@ -89,7 +90,48 @@ export declare class LibsUiGridLayoutCanvasComponent implements AfterViewInit, O
     readonly outConfigNode: import("@angular/core").OutputEmitterRef<T_gridLayout_actionEvent>;
     private readonly gridsterRef;
     private readonly scrollAreaRef;
+    /**
+     * Cầm BẤT CỨ ĐÂU trên khối để kéo, thay cho dải kéo ba chấm.
+     *
+     * 🔴 Mặc định `false` — giữ nguyên luật đã chốt 28/08/2026 cho mọi sản phẩm: *"phải hover vào vùng
+     * màu xanh thì mới kéo thả được cho đồng nhất"*. Nơi dùng nào muốn kiểu "cầm vào thẻ là kéo" thì tự
+     * bật, không đổi hành vi của màn khác.
+     *
+     * Bật lên thì dải kéo biến mất và gridster chuyển sang `ignoreContent: false` — cho kéo từ mọi chỗ
+     * TRỪ phần tử mang `ignoreContentClass`. Nhờ vậy khối con nằm trong khối ghép vẫn không nhấc nhầm
+     * khối ghép: vỏ khối con đã mang sẵn class chặn đó.
+     */
+    readonly dragFromAnywhere: import("@angular/core").InputSignal<boolean>;
+    /**
+     * Nơi dùng đã đẩy vùng cuộn DỌC vào thẳng `<gridster>` (bằng CSS của chính nó).
+     *
+     * 🔴 Bật cờ này là trả `angular-gridster2` về đúng giả định gốc của nó — `dragMove` đọc
+     * `gridster.el.scrollTop`, `scroll()` đo `gridsterElement.offsetHeight` — nên thư viện KHÔNG bắc
+     * cầu `scrollTop` sang khung bọc nữa, và vòng tự cuộn khi kéo cũng cuộn thẳng vào gridster.
+     *
+     * 🔴 PHẢI là input, KHÔNG dò bằng `getComputedStyle`: thanh cuộn nổi của libs-ui mới là thứ đặt
+     * `overflow` lên phần tử, mà nó chạy SAU `ngAfterViewInit` — dò lúc đó luôn ra "không cuộn" và cầu
+     * nối vẫn cắm vào, nuốt sạch đoạn cuộn thật (đo 15/09/2026: `g.scrollTop = 300` xong đọc lại vẫn 0).
+     */
+    readonly gridsterOwnsScroll: import("@angular/core").InputSignal<boolean>;
+    /**
+     * Vẽ thanh cuộn nổi của libs-ui cho mặt phẳng LỒNG (ruột khối ghép).
+     *
+     * 🔴 Vùng cuộn của mặt phẳng lồng phải giấu thanh cuộn mặc định của trình duyệt — nó dày, xám, và
+     * ăn mất bề rộng của lưới con nên 24 cột hẹp lại mỗi khi nội dung vừa đủ tràn. Hệ quả là người
+     * dùng cuộn được nhưng KHÔNG THẤY có gì để cuộn: thẻ con nằm dưới đáy trông như biến mất (người
+     * dùng chỉ ra 16/09/2026). Bật cờ này để thư viện gắn thanh cuộn nổi — nhìn thấy được mà không
+     * chiếm chỗ.
+     */
+    readonly nestedScrollbar: import("@angular/core").InputSignal<boolean>;
     private readonly zoomDockRef;
+    /** Gỡ cầu nối scroll đã cắm lên phần tử `<gridster>` — xem `bridgeScrollToGridster`. */
+    private removeScrollBridge;
+    /** Gỡ vòng tự cuộn khi kéo — xem `startDragAutoScroll`. */
+    private stopDragAutoScroll;
+    /** Khoảng cách tới mép vùng cuộn (px) bắt đầu tự cuộn, và bước cuộn mỗi khung hình. */
+    private readonly dragScrollEdge;
+    private readonly dragScrollStep;
     /** mỗi ô một chỗ gắn riêng — cùng thứ tự với `children()` */
     private readonly itemHosts;
     /**
@@ -137,6 +179,13 @@ export declare class LibsUiGridLayoutCanvasComponent implements AfterViewInit, O
      */
     protected readonly toolbarContexts: import("@angular/core").Signal<T_gridLayout_toolbarContext[]>;
     protected readonly isNestedCanvas: import("@angular/core").Signal<boolean>;
+    /** Chỉ mặt phẳng LỒNG mới vẽ thanh cuộn nổi — mặt phẳng gốc do nơi dùng tự lo. */
+    protected readonly showNestedScrollbar: import("@angular/core").Signal<boolean>;
+    /**
+     * Chỉ cuộn DỌC: bề rộng khối con luôn bị gridster kẹp trong số cột của lưới nên không có gì để
+     * cuộn ngang.
+     */
+    protected readonly nestedScrollOverlayOptions: IScrollOverlayOptions;
     /**
      * Khe nhìn thấy giữa các khối CẤP GỐC. Mặt phẳng lồng trả 0 — khối con là các dòng của cùng một
      * thẻ, tách chúng ra làm chúng trông như thẻ rời.
@@ -168,6 +217,40 @@ export declare class LibsUiGridLayoutCanvasComponent implements AfterViewInit, O
         setZoom: (val: number) => void;
         scrollArea: () => HTMLElement | undefined;
     };
+    /**
+     * Bắc CẦU NỐI để `<gridster>` báo cáo scroll của KHUNG CUỘN, thay vì scroll của chính nó.
+     *
+     * 🔴 Vì sao cần: gridster đổi vị trí chuột thành ô lưới bằng
+     * `e.clientY + (el.scrollTop - el.offsetTop)` (xem `calculateItemPositionWithoutScale` và
+     * `this.offsetTop = this.gridster.el.scrollTop - this.gridster.el.offsetTop` trong
+     * `angular-gridster2@18`). Công thức chỉ đúng khi CHÍNH `<gridster>` là phần tử cuộn — đúng như
+     * comment đã ghi ở template cho `offsetParent`. Ở nhánh THU PHÓNG, việc cuộn nằm ở `#scrollArea`
+     * còn `<gridster>` giữ đủ cỡ sân khấu bên trong một tầng `transform: scale`, nên
+     * `el.scrollTop` luôn bằng 0: mọi px người dùng cuộn đều vô hình với thư viện. Hệ quả đo được
+     * 15/09/2026 trên mặt phẳng cấp trang: tự cuộn lúc kéo không chạy, và nếu nơi dùng tự cuộn thì thẻ
+     * đứng im trong khi mặt phẳng trôi.
+     *
+     * 🔴 CHỈ vá `scrollTop`/`scrollLeft`. CẤM đụng `offsetWidth`/`offsetHeight`: `setGridSize()` của
+     * gridster đọc hai cái đó để tính `curColWidth`, đè vào là vỡ bề rộng cột của mọi lưới.
+     *
+     * 🔴 Chia cho mức phóng: `offsetTop` là px BỐ CỤC, còn `scrollTop` của khung cuộn là px đã nhân
+     * thu phóng. Không quy đổi thì ở mức phóng khác 100% khối trôi nhanh hơn hoặc chậm hơn con trỏ.
+     */
+    /** Phần tử thật sự cuộn theo chiều dọc — `<gridster>` nếu nơi dùng đã đẩy cuộn vào trong nó. */
+    private vungCuonDoc;
+    private bridgeScrollToGridster;
+    /**
+     * Tự cuộn mặt phẳng khi người dùng kéo khối tới sát mép.
+     *
+     * 🔴 Tự cuộn sẵn có của gridster (`scrollSensitivity`) không dùng được ở nhánh thu phóng: hàm
+     * `scroll()` của nó đo bằng `gridsterElement.offsetHeight`, mà `<gridster>` cao bằng CẢ sân khấu
+     * nên con trỏ không bao giờ "tới sát mép" theo con mắt của nó.
+     *
+     * 🔴 Chỉ cuộn khi thư viện ĐANG kéo thật (`.gridster-item-moving`) — không có chốt này thì một cú
+     * bấm bình thường gần mép cũng làm mặt phẳng trôi.
+     */
+    protected handlerScrollAreaPointerDown(): void;
+    private startDragAutoScroll;
     protected handlerZoomIn(): void;
     protected handlerZoomOut(): void;
     protected handlerResetZoom(): void;
@@ -234,5 +317,5 @@ export declare class LibsUiGridLayoutCanvasComponent implements AfterViewInit, O
     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; }; "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>;
+    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; }; "dragFromAnywhere": { "alias": "dragFromAnywhere"; "required": false; "isSignal": true; }; "gridsterOwnsScroll": { "alias": "gridsterOwnsScroll"; "required": false; "isSignal": true; }; "nestedScrollbar": { "alias": "nestedScrollbar"; "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/scroll-bridge.define.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Cầu nối cho phép một phần tử BÁO CÁO scroll của phần tử khác.
+ *
+ * 🔴 Vì sao tồn tại: `angular-gridster2` đổi vị trí chuột thành ô lưới bằng
+ * `e.clientY + (el.scrollTop - el.offsetTop)` — công thức chỉ đúng khi CHÍNH `<gridster>` là phần tử
+ * cuộn. Ở mặt phẳng có THU PHÓNG, việc cuộn nằm ở khung bọc còn `<gridster>` giữ đủ cỡ sân khấu bên
+ * trong một tầng `transform: scale`, nên `el.scrollTop` luôn bằng 0: mọi px người dùng cuộn đều vô
+ * hình với thư viện. Hệ quả đo được 15/09/2026: tự cuộn lúc kéo không chạy, và nếu nơi dùng tự cuộn
+ * thì khối đứng im trong khi mặt phẳng trôi.
+ *
+ * 🔴 CHỈ vá `scrollTop`/`scrollLeft`. CẤM đụng `offsetWidth`/`offsetHeight`: `setGridSize()` của
+ * gridster đọc hai cái đó để tính bề rộng cột, đè vào là vỡ lưới.
+ */
+/**
+ * Cắm cầu nối, trả về hàm gỡ.
+ *
+ * `zoom` là hàm chứ không phải số: mức phóng đổi bất cứ lúc nào, đọc lại mỗi lần truy cập mới đúng.
+ * Chia cho mức phóng vì `offsetTop` là px BỐ CỤC còn scroll của khung bọc đã nhân thu phóng — không
+ * quy đổi thì ở mức khác 100% khối trôi nhanh hơn hoặc chậm hơn con trỏ.
+ */
+export declare const bridgeScrollBetweenElements: (target: HTMLElement, source: HTMLElement, zoom: () => number) => (() => void);
+/**
+ * Bước cuộn cho một trục khi con trỏ đang ở sát mép vùng cuộn.
+ *
+ * Trả `0` khi con trỏ còn ở giữa. Mép DƯỚI/PHẢI được soát trước: con trỏ ra ngoài hẳn khung thì
+ * `pos` vượt `max`, phải cuộn xuôi chứ không phải ngược.
+ */
+export declare const edgeScrollStep: (options: {
+    pos: number;
+    min: number;
+    max: number;
+    edge: number;
+    step: number;
+}) => number;