@shival99/z-ui 2.2.1 → 2.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shival99/z-ui",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "Z-UI: Modern Angular UI Component Library - A comprehensive, high-performance design system built with Angular 22, featuring 40+ customizable components with dark mode, accessibility, and enterprise-ready features.",
   "keywords": [
     "angular",

package/types/shival99-z-ui-components-z-chat.d.ts

@@ -1,3 +1,4 @@
+import * as _tanstack_angular_virtual from '@tanstack/angular-virtual';
 import * as _angular_core from '@angular/core';
 import { OnDestroy } from '@angular/core';
 import { ZIcon } from '@shival99/z-ui/components/z-icon';
@@ -81,9 +82,22 @@ declare class ZChatComponent implements OnDestroy {
     private readonly _messagesScrollbarRef;
     private readonly _chatInputRef;
     private readonly _fileInputRef;
+    private readonly _virtualMessageRefs;
+    /** Signal, not a field: requesting a pin must itself wake `_pinToNewest`. */
+    private readonly _pinAttemptsLeft;
     private _mockReplyTimer;
     private _rippleTimer;
-    private _scrollTimer;
+    private readonly _measureMessages;
+    protected readonly messageVirtualizer: _tanstack_angular_virtual.AngularVirtualizer<HTMLElement, Element>;
+    /**
+     * Drives a requested pin to completion across renders.
+     *
+     * One `scrollToEnd()` is not enough on a cold list: the end is computed from estimates, and it
+     * moves as rows are measured. The scroll box also arrives late — ng-scrollbar reports its
+     * viewport only after init, and a scroll issued before then leaves the virtualizer at offset 0
+     * with no event to resync it. Re-asserting each render until `isAtEnd` holds covers both.
+     */
+    private readonly _pinToNewest;
     protected readonly wrapperClasses: _angular_core.Signal<string>;
     protected readonly wrapperTop: _angular_core.Signal<string | null>;
     protected readonly wrapperRight: _angular_core.Signal<string | null>;
@@ -94,6 +108,8 @@ declare class ZChatComponent implements OnDestroy {
     protected readonly isTyping: _angular_core.Signal<boolean>;
     protected readonly canSend: _angular_core.Signal<boolean>;
     protected readonly hasMessages: _angular_core.Signal<boolean>;
+    /** Only the newest bubble plays the push-in animation; recycled rows must not replay it. */
+    protected readonly newestMessageId: _angular_core.Signal<string | null>;
     protected readonly showEmptyState: _angular_core.Signal<boolean>;
     protected readonly previewImageSizeLabel: _angular_core.Signal<string>;
     ngOnDestroy(): void;
@@ -120,9 +136,16 @@ declare class ZChatComponent implements OnDestroy {
     private _triggerRipple;
     protected onMessagesScrollbarInit(): void;
     protected onEscapeKey(): void;
-    private _scheduleScrollToBottom;
+    /**
+     * Requests a pin to the newest message; `_pinToNewest` performs it once rendering can honour it.
+     *
+     * Never scroll synchronously from here. Callers fire right after mutating `zMessages` or
+     * `zOpen`, before change detection has fed the new length into the virtualizer, so the scroll
+     * would target the previous last index and strand the list mid-history.
+     */
     private _ensureBottomVisible;
-    private _scrollToBottom;
+    /** ng-scrollbar owns the real scrolling box; the virtualizer must observe that, not the host. */
+    private _getMessagesViewportElement;
     private _focusInputSoon;
     private _releaseAttachmentUrls;
     private _appendFiles;

package/types/shival99-z-ui-components-z-table.d.ts

@@ -458,6 +458,13 @@ interface ZTableGroupingConfig<T = unknown> {
     allowHeaderMenu?: boolean;
     defaultExpanded?: boolean;
     showCount?: boolean;
+    /**
+     * Ghim group header đang active lên đầu vùng cuộn (chạy ở cả virtual lẫn non-virtual).
+     * Header của group hiện tại dính ở đầu bảng và bị group kế tiếp đẩy đi khi cuộn tới.
+     * Multi-level grouping thì header con xếp chồng ngay dưới header cha.
+     * @default false
+     */
+    stickyHeader?: boolean;
     /** Cấu hình các cột cần hiển thị tổng trên group row. */
     totals?: ZTableGroupTotalConfig<T>[];
     /**
@@ -1115,6 +1122,7 @@ declare class ZTableComponent<T> implements AfterViewInit {
     private readonly _zTranslate;
     /** Prevents recursive scroll sync between thead/tbody/tfoot */
     private readonly _isSyncingScroll;
+    private _lastSyncedScrollLeft;
     /** Preserves horizontal scroll position across loading states */
     private readonly _savedScrollLeft;
     /** Observes tbody container height changes for skeleton row count calculation */
@@ -1150,6 +1158,7 @@ declare class ZTableComponent<T> implements AfterViewInit {
     protected readonly tfootWrapper: _angular_core.Signal<ElementRef<HTMLDivElement> | undefined>;
     protected readonly expandedRowTemplate: _angular_core.Signal<TemplateRef<unknown> | undefined>;
     protected readonly virtualRowElements: _angular_core.Signal<readonly ElementRef<HTMLDivElement>[]>;
+    protected readonly groupRowElements: _angular_core.Signal<readonly ElementRef<HTMLTableRowElement>[]>;
     protected readonly columnPinning: _angular_core.WritableSignal<ColumnPinningState>;
     protected readonly columnVisibility: _angular_core.WritableSignal<ColumnVisibilityState>;
     protected readonly columnOrder: _angular_core.WritableSignal<ColumnOrderState>;
@@ -1241,6 +1250,21 @@ declare class ZTableComponent<T> implements AfterViewInit {
     protected readonly hasScrollTop: _angular_core.WritableSignal<boolean>;
     /** True khi bottom-pinned rows đang đè lên nội dung body còn scroll xuống được */
     protected readonly hasScrollBottom: _angular_core.WritableSignal<boolean>;
+    /**
+     * Group header (non-virtual) đang ghim ở mép dưới cùng của chồng sticky — chỉ mình nó đổ shadow.
+     * Nhiều header ghim chung một chỗ, mỗi cái một shadow thì alpha cộng dồn thành vệt đen đậm dần.
+     * Chỉ dùng cho shadow: class này bám theo scroll nên luôn trễ một frame, chấp nhận được với shadow
+     * nhưng không dùng được cho z-index (xem `tr.z-group-row-sticky`).
+     */
+    protected readonly shadowGroupRowId: _angular_core.WritableSignal<string | null>;
+    /** Chiều cao thật của group header row (non-virtual), dùng để xếp chồng sticky theo depth. */
+    private readonly _groupRowHeight;
+    /**
+     * Tổng chiều cao khối pinned top rows (non-virtual), đo trực tiếp từ DOM sau mỗi render.
+     * Không dùng `pinnedRowHeights` vì signal đó chỉ refresh trong `_checkScrollState`, nên có thể
+     * còn giữ số đo cũ khi bảng vừa đổi cấu hình — sticky group header sẽ hở một khoảng vài px.
+     */
+    private readonly _nonVirtualPinnedTopHeight;
     /** Maps row IDs to measured DOM heights for pinned row offset calculations */
     protected readonly pinnedRowHeights: _angular_core.WritableSignal<Record<string, number>>;
     protected readonly virtualMeasuredLeftSpacerWidth: _angular_core.WritableSignal<number>;
@@ -1357,6 +1381,40 @@ declare class ZTableComponent<T> implements AfterViewInit {
     protected readonly renderedBodyRows: _angular_core.Signal<Row<T>[]>;
     protected readonly bodyRowSpanRows: _angular_core.Signal<Row<T>[]>;
     protected readonly virtualGroupedFlatItems: _angular_core.Signal<ZVirtualFlatItem<T>[]>;
+    /** Sticky group header đang bật (config cho phép và đang thực sự group theo cột nào đó). */
+    protected readonly isStickyGroupHeaderEnabled: _angular_core.Signal<boolean>;
+    /** Flow layout: một transform cho cả khối thay vì mỗi row một cái. Sticky group header phải
+     * dùng absolute vì rangeExtractor làm tập render không liền mạch. */
+    protected readonly usesFlowVirtualRows: _angular_core.Signal<boolean>;
+    protected readonly virtualFlowOffset: _angular_core.Signal<number>;
+    /**
+     * `top` (px) của sticky group header theo depth ở chế độ non-virtual.
+     * Ở đây mọi group header đều là `<tr>` thật trong cùng một `<tbody>`, nên chỉ cần `position: sticky`:
+     * header sau (đứng sau trong DOM) tự đè lên header trước khi trôi tới rồi lộ lại khi cuộn ngược —
+     * không cần rangeExtractor như bên virtual (cơ chế đó chỉ để giữ row đã ra khỏi range).
+     * Header con xếp chồng ngay dưới header cha nên cộng thêm `depth * chiều cao group row`.
+     */
+    protected readonly stickyGroupTopByDepth: _angular_core.Signal<number[]>;
+    /**
+     * Lookup phục vụ sticky group header trong virtual scroll:
+     * - `nearest[i]`: index group header gần nhất tại hoặc trước `i` (-1 nếu chưa có).
+     * - `parent`: index group header cha của một header (multi-level grouping), -1 nếu là cấp gốc.
+     * Trả `null` khi tắt sticky hoặc không ở chế độ virtual + grouping.
+     */
+    private readonly _stickyGroupHeaderMeta;
+    /** Chuỗi header (gốc → sâu nhất) cần ghim khi viewport bắt đầu tại `startIndex`. */
+    private _buildStickyGroupChain;
+    /**
+     * Trạng thái sticky group header theo virtual index:
+     * - `tops`: offset `top` (px) của từng header đang ghim; header cấp sâu hơn xếp chồng bên dưới
+     *   header cha nên cộng dồn chiều cao.
+     * - `shadowIndex`: header cuối chuỗi mang shadow (giống pinned row), -1 khi chưa có row nào
+     *   cuộn xuống dưới nó — lúc đó header vẫn ở đúng vị trí thật nên không cần shadow.
+     */
+    protected readonly stickyGroupHeaderState: _angular_core.Signal<{
+        shadowIndex: number;
+        tops: Record<number, number>;
+    }>;
     protected _getVirtualGroupHeader(item: ZVirtualFlatItem<T> | undefined): ZTableGroupRowItem | null;
     protected _isVirtualGroupChild(item: ZVirtualFlatItem<T> | undefined): boolean;
     protected _getVirtualGroupDepth(item: ZVirtualFlatItem<T> | undefined): number;
@@ -1629,6 +1687,16 @@ declare class ZTableComponent<T> implements AfterViewInit {
         rowSelectionFeature: _tanstack_angular_table.TableFeature;
         rowSortingFeature: _tanstack_angular_table.TableFeature;
     }, T & Record<string, unknown>>[]>;
+    /**
+     * Id row ở hai biên của mỗi khối pinned, theo THỨ TỰ HIỂN THỊ (pinned bottom render ngược lại).
+     * Dùng signal thay cho `zTableRow` pipe: pipe là pure, chỉ chạy lại khi một tham số đổi reference.
+     * Khi ghim thêm/bớt row thì `row` và `table` giữ nguyên reference, nên row từng là biên vẫn giữ
+     * class cũ — pin bottom lộ rõ nhất vì shadow ở lại row cũ và row mới cũng có shadow.
+     */
+    protected readonly firstTopPinnedRowId: _angular_core.Signal<string>;
+    protected readonly lastTopPinnedRowId: _angular_core.Signal<string>;
+    protected readonly firstBottomPinnedRowId: _angular_core.Signal<string>;
+    protected readonly lastBottomPinnedRowId: _angular_core.Signal<string>;
     protected readonly leftHeaderRow: _angular_core.Signal<_tanstack_angular_table.Header<{
         expandedRowModel: (table: _tanstack_angular_table.Table<any, any>) => () => _tanstack_angular_table.RowModel<any, any>;
         facetedMinMaxValues: (table: _tanstack_angular_table.Table<_tanstack_angular_table.TableFeatures, any>, columnId: string) => () => undefined | [number, number];
@@ -1795,9 +1863,43 @@ declare class ZTableComponent<T> implements AfterViewInit {
     protected readonly effectiveDynamicRowSizing: _angular_core.Signal<boolean>;
     /** Virtualizer instance — operates on groups rather than individual rows */
     protected readonly virtualizer: _tanstack_angular_virtual.AngularVirtualizer<HTMLElement, Element>;
+    /**
+     * Nhận diện group header đang ghim sau MỖI render, không chỉ khi scroll.
+     * Đổi virtual/non-virtual, đổi cột group hay pin/unpin row đều giữ nguyên scrollOffset nhưng dựng
+     * lại DOM và đổi đường sticky — nếu chỉ trông vào scroll handler thì header đang ghim sẽ thiếu
+     * class `z-group-row-stuck` cho tới lần cuộn kế tiếp, và bị data row đè trong khoảng đó.
+     * `_refreshStuckGroupRows` đọc `groupRowElements` + `stickyGroupTopByDepth` trước mọi early-return
+     * nên effect này tự chạy lại khi hai nguồn đó đổi (kể cả khi số đo tới muộn hơn một pass).
+     */
+    private readonly _trackStuckGroupRows;
+    /** Measures in the render `read` phase so corrected offsets land before paint, not a frame later. */
     private readonly _measureVirtualItems;
-    /** Learn estimate height from measured rows (reads the measurement cache, no reflow). Locks once. */
-    private _learnDynamicEstimate;
+    private _stuckGroupRowsFrame;
+    /** Gom nhiều lần scroll trong cùng một frame — mỗi lần chạy đều đọc rect nên phải giới hạn tần suất. */
+    private _scheduleStuckGroupRowsRefresh;
+    private _cancelStuckGroupRowsRefresh;
+    /**
+     * Tìm group header (non-virtual) đang ghim ở mép dưới cùng của chồng sticky để trao shadow.
+     * Header đã ghim có `rect.top` đúng bằng đường sticky của depth đó; header chưa tới thì lớn hơn.
+     * Ưu tiên đường sticky thấp nhất (multi-level: header con), tie thì lấy cái sau cùng trong DOM vì
+     * đó là cái đang nằm trên khi nhiều header chồng nhau.
+     */
+    private _refreshStuckGroupRows;
+    /** Đo các mốc mà `stickyGroupTopByDepth` cần (non-virtual): chiều cao group row và khối pinned top. */
+    private _refreshStickyGroupMetrics;
+    private _hasWarnedOverflowingFixedRows;
+    /**
+     * Cảnh báo một lần mỗi bảng khi body row cao hơn `virtual.size`.
+     * CSS table layout coi `height` trên `<tr>`/`<td>` là min-height, nên nội dung cell không nén được
+     * (tag, button, nhiều dòng…) sẽ đẩy row vượt slot của virtualizer; row kế tiếp định vị tuyệt đối
+     * đúng theo `virtual.size` nên đè lên phần dôi ra — nhìn như mỗi row bị hụt mất vài px.
+     * Không tự sửa: chiều cao đúng phụ thuộc dữ liệu, chọn tăng `size` hay bật `dynamicSize` là của app.
+     */
+    private _warnOnOverflowingFixedRows;
+    private _dynamicEstimateSampleCount;
+    /** Averages the rows measured so far to estimate the ones not yet rendered.
+     * Tính lại theo bậc ~1.5x để tổng công việc là O(N) thay vì O(N²) khi cuộn hết danh sách dài. */
+    private _refreshDynamicEstimate;
     private readonly _rowDragAutoScroll;
     private readonly _rowDragCellSelectionCleanup;
     constructor();
@@ -2039,11 +2141,11 @@ declare class ZTableFilterComponent<T> {
     protected readonly sortOptions: _angular_core.Signal<ZSelectOption<string>[]>;
     protected readonly draftFilters: _angular_core.WritableSignal<ZTableDraftFilterCondition[]>;
     protected readonly draftLegacyFilterValue: _angular_core.WritableSignal<unknown>;
-    protected readonly draftSortState: _angular_core.WritableSignal<false | "asc" | "desc">;
+    protected readonly draftSortState: _angular_core.WritableSignal<false | "desc" | "asc">;
     protected readonly columnFilterValue: _angular_core.Signal<unknown>;
     protected readonly effectiveFilterValue: _angular_core.Signal<unknown>;
-    protected readonly sortState: _angular_core.Signal<false | "asc" | "desc">;
-    protected readonly effectiveSortState: _angular_core.Signal<false | "asc" | "desc">;
+    protected readonly sortState: _angular_core.Signal<false | "desc" | "asc">;
+    protected readonly effectiveSortState: _angular_core.Signal<false | "desc" | "asc">;
     protected readonly canSort: _angular_core.Signal<boolean>;
     protected readonly canFilter: _angular_core.Signal<boolean>;
     protected readonly filterUi: _angular_core.Signal<ZTableFilterUi>;
@@ -2061,7 +2163,7 @@ declare class ZTableFilterComponent<T> {
     protected readonly filterBadgeCount: _angular_core.Signal<number>;
     protected readonly hasFilterValue: _angular_core.Signal<boolean>;
     protected readonly isActive: _angular_core.Signal<boolean>;
-    protected readonly draftSortValue: _angular_core.Signal<"asc" | "desc" | "none">;
+    protected readonly draftSortValue: _angular_core.Signal<"none" | "desc" | "asc">;
     protected readonly rangeMinValue: _angular_core.Signal<any>;
     protected readonly rangeMaxValue: _angular_core.Signal<any>;
     protected readonly dateValue: _angular_core.Signal<Date | null>;