@shival99/z-ui 2.0.67 → 2.0.68

package/package.json

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

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

@@ -364,6 +364,26 @@ interface ZTablePaginationConfig {
     disabled?: boolean;
 }
 type ZTableGroupingMode = 'local' | 'server';
+/**
+ * EN: Server-provided group descriptor. In server grouping the table does NOT compute groups from
+ *     the current page rows; instead the parent supplies the ordered group list (label/count) and
+ *     fills `config.data` with the child rows it has fetched. Rows are matched to a group by `value`
+ *     (same key the grouping column would produce) — i.e. row.getValue(groupingColumnId) === group.value.
+ * VI: Mô tả group do server cung cấp. Ở chế độ server, table KHÔNG tự group từ rows của trang hiện
+ *     tại; parent cung cấp danh sách group (label/count) theo thứ tự và đổ child rows đã fetch vào
+ *     `config.data`. Row được gán vào group qua `value` (cùng key mà cột group sinh ra) — tức
+ *     row.getValue(groupingColumnId) === group.value.
+ */
+interface ZTableServerGroup {
+    /** Giá trị nhóm — khớp với row.getValue(groupingColumnId) để gán row vào group. */
+    value: unknown;
+    /** Nhãn hiển thị; nếu bỏ trống table tự suy ra từ `value`. */
+    label?: string;
+    /** Tổng số dòng của group (server cung cấp) — hiển thị badge kể cả khi chưa expand/đủ data. */
+    count?: number;
+    /** Đang fetch rows cho group này (hiển thị loading trong group). */
+    loading?: boolean;
+}
 interface ZTableGroupingConfig {
     enabled?: boolean;
     mode?: ZTableGroupingMode;
@@ -371,6 +391,20 @@ interface ZTableGroupingConfig {
     allowHeaderMenu?: boolean;
     defaultExpanded?: boolean;
     showCount?: boolean;
+    /**
+     * Cột đang group ở chế độ server (bắt buộc cho server grouping vì table không tự suy ra).
+     * Nếu bỏ trống, dùng phần tử đầu của `columns`.
+     */
+    serverGroupColumnId?: string;
+    /** Danh sách group do server cung cấp (chỉ dùng khi mode = 'server'). */
+    serverGroups?: ZTableServerGroup[];
+}
+/** Payload emit khi expand/collapse một group ở chế độ server. */
+interface ZTableGroupExpandEvent {
+    groupId: string;
+    columnId: string;
+    value: unknown;
+    expanded: boolean;
 }
 /** Distinguishes user-triggered vs programmatic pagination changes */
 type ZTableEmitType = 'user' | 'auto';
@@ -593,7 +627,7 @@ interface ZTableActionColumnConfig<T = unknown> {
 }
 type ZTableActionBodyConfig<T = unknown> = ZTableActionColumnConfig<T> | (ZTableActionList<T> & Partial<ZTableActionColumnConfig<T>>);
 /** All possible change event types — used as discriminant in ZTableChangeEvent */
-type ZTableChangeType = 'page' | 'sort' | 'filter' | 'search' | 'select' | 'expand' | 'rowSelect' | 'rowSelectAll' | 'rowExpand' | 'rowDrag' | 'rowInsert' | 'rowDelete' | 'rowCopy' | 'rowPaste' | 'rowMove' | 'cellClick' | 'cellEdit' | 'action' | 'bulkAction' | 'grouping';
+type ZTableChangeType = 'page' | 'sort' | 'filter' | 'search' | 'select' | 'expand' | 'rowSelect' | 'rowSelectAll' | 'rowExpand' | 'rowDrag' | 'rowInsert' | 'rowDelete' | 'rowCopy' | 'rowPaste' | 'rowMove' | 'cellClick' | 'cellEdit' | 'action' | 'bulkAction' | 'grouping' | 'groupExpand';
 interface ZTableChangeEventBase {
     type: ZTableChangeType;
 }
@@ -671,6 +705,10 @@ interface ZTableGroupingChange extends ZTableChangeEventBase {
         grouping: string[];
     };
 }
+interface ZTableGroupExpandChange extends ZTableChangeEventBase {
+    type: 'groupExpand';
+    data: ZTableGroupExpandEvent;
+}
 interface ZTableActionChange<T> extends ZTableChangeEventBase {
     type: 'action';
     data: ZTableActionClickEvent<T>;
@@ -696,7 +734,7 @@ interface ZTableCellEditChange<T> extends ZTableChangeEventBase {
  * }
  * ```
  */
-type ZTableChangeEvent<T> = ZTablePageChange | ZTableSortChange | ZTableFilterChange | ZTableSearchChange | ZTableSelectChange | ZTableExpandChange | ZTableGroupingChange | ZTableRowSelectChange<T> | ZTableRowSelectAllChange<T> | ZTableRowExpandChange<T> | ZTableRowDragChange<T> | ZTableRowInsertChange<T> | ZTableRowDeleteChange<T> | ZTableRowCopyChange<T> | ZTableRowPasteChange<T> | ZTableRowMoveChange<T> | ZTableCellClickChange<T> | ZTableCellEditChange<T> | ZTableActionChange<T> | ZTableBulkActionChange<T>;
+type ZTableChangeEvent<T> = ZTablePageChange | ZTableSortChange | ZTableFilterChange | ZTableSearchChange | ZTableSelectChange | ZTableExpandChange | ZTableGroupingChange | ZTableGroupExpandChange | ZTableRowSelectChange<T> | ZTableRowSelectAllChange<T> | ZTableRowExpandChange<T> | ZTableRowDragChange<T> | ZTableRowInsertChange<T> | ZTableRowDeleteChange<T> | ZTableRowCopyChange<T> | ZTableRowPasteChange<T> | ZTableRowMoveChange<T> | ZTableCellClickChange<T> | ZTableCellEditChange<T> | ZTableActionChange<T> | ZTableBulkActionChange<T>;
 /** Initial table state — applied on first render, before any cached config is loaded */
 interface ZTableInitialState {
     columnPinning?: ColumnPinningState;
@@ -911,6 +949,8 @@ interface ZTableGroupRowItem {
     columnLabel: string;
     count: number;
     expanded: boolean;
+    /** Server grouping: group đang fetch child rows. */
+    loading?: boolean;
 }
 interface ZTableDataRowItem<T> {
     type: 'row';
@@ -1128,10 +1168,21 @@ declare class ZTableComponent<T> implements AfterViewInit {
     protected readonly hasLocalSorting: _angular_core.Signal<boolean>;
     protected readonly hasServerFiltering: _angular_core.Signal<boolean>;
     protected readonly groupingConfig: _angular_core.Signal<ZTableGroupingConfig>;
+    /** EN/VI: true khi grouping chạy ở chế độ server (group meta do server cung cấp). */
+    protected readonly isServerGrouping: _angular_core.Signal<boolean>;
     protected readonly canUseGrouping: _angular_core.Signal<boolean>;
+    /** EN/VI: cột group hiệu lực cho chế độ server (config cung cấp, không suy ra từ data). */
+    protected readonly serverGroupColumnId: _angular_core.Signal<string | null>;
     protected readonly activeGroupingColumnId: _angular_core.Signal<string | null>;
     protected readonly groupableColumnMap: _angular_core.Signal<Record<string, boolean>>;
     protected readonly groupedCenterRowItems: _angular_core.Signal<ZTableGroupedRowItem<T>[]>;
+    /** Local grouping: group được tính tại client từ rows của trang hiện tại. */
+    private _buildLocalGroupedItems;
+    /**
+     * Server grouping: thứ tự & meta group do `config.enableGrouping.serverGroups` quyết định.
+     * Child rows lấy từ `getCenterRows()` (data parent đã fetch) và gán vào group theo value.
+     */
+    private _buildServerGroupedItems;
     /**
      * EN: Flat list of body rows in the exact order they are rendered. When grouping is active the
      *     center rows are re-ordered group-by-group, so the flat `table.getRowModel().rows` no longer
@@ -1526,7 +1577,7 @@ declare class ZTableActionsComponent<T = unknown> {
     readonly zConfig: _angular_core.InputSignal<ZTableActionColumnConfig<T>>;
     readonly zRow: _angular_core.InputSignal<T>;
     readonly zRowId: _angular_core.InputSignal<string>;
-    readonly zDropdownButtonSize: _angular_core.InputSignal<"default" | "sm" | "lg" | "xs" | "xl" | null | undefined>;
+    readonly zDropdownButtonSize: _angular_core.InputSignal<"sm" | "default" | "lg" | "xs" | "xl" | null | undefined>;
     readonly zActionClick: _angular_core.OutputEmitterRef<ZTableActionClickEvent<T>>;
     protected readonly allActions: _angular_core.Signal<ZTableActionItem<T>[]>;
     protected readonly shouldShowAsButtons: _angular_core.Signal<boolean>;
@@ -1680,4 +1731,4 @@ declare const findColumnConfig: <T>(columnId: string, columns: ZTableColumnConfi
 declare function columnConfigToColumnDef<T>(config: ZTableColumnConfig<T>): ColumnDef<T>;
 
 export { ZTableActionsComponent, ZTableComponent, ZTableEditCellComponent, ZTableFilterComponent, ZTableIconTextComponent, columnConfigToColumnDef, findColumnConfig, getBodyConfig, getFooterConfig, getHeaderConfig, isBodyConfig, isFooterConfig, isHeaderConfig };
-export type { ZTableActionBodyConfig, ZTableActionClickEvent, ZTableActionColumnConfig, ZTableActionItem, ZTableActionList, ZTableAdvancedFilterType, ZTableBodyContentType, ZTableBulkActionClickEvent, ZTableBulkActionConfig, ZTableBulkActionContext, ZTableBulkActionHandlerContext, ZTableBulkActionItem, ZTableBulkActionList, ZTableBulkActionOptions, ZTableBulkActionViewItem, ZTableCellEditChange, ZTableCellEditEvent, ZTableChangeEvent, ZTableColumn, ZTableColumnConfig, ZTableConfig, ZTableControl, ZTableEditCellChangeEvent, ZTableEditConfig, ZTableEditContentConfig, ZTableEditContentType, ZTableEditSize, ZTableEditType, ZTableExcelExportConfig, ZTableExcelExportContext, ZTableExcelExportScope, ZTableFilterChangeEvent, ZTableFilterCondition, ZTableFilterConfig, ZTableFilterJoinOperator, ZTableFilterOperator, ZTableFilterOptionSource, ZTableFilterUi, ZTableFilterValueType, ZTablePageChangeEvent, ZTablePaginationConfig, ZTableRowCopyChange, ZTableRowCopyEvent, ZTableRowDeleteChange, ZTableRowDeleteEvent, ZTableRowExpandEvent, ZTableRowInsertChange, ZTableRowInsertEvent, ZTableRowInsertPosition, ZTableRowMoveChange, ZTableRowMoveDirection, ZTableRowMoveEvent, ZTableRowPasteChange, ZTableRowPasteEvent, ZTableRowSelectEvent, ZTableSearchChangeEvent, ZTableSearchConfig, ZTableSortChangeEvent, ZTableSortConfig, ZTableTagColor };
+export type { ZTableActionBodyConfig, ZTableActionClickEvent, ZTableActionColumnConfig, ZTableActionItem, ZTableActionList, ZTableAdvancedFilterType, ZTableBodyContentType, ZTableBulkActionClickEvent, ZTableBulkActionConfig, ZTableBulkActionContext, ZTableBulkActionHandlerContext, ZTableBulkActionItem, ZTableBulkActionList, ZTableBulkActionOptions, ZTableBulkActionViewItem, ZTableCellEditChange, ZTableCellEditEvent, ZTableChangeEvent, ZTableColumn, ZTableColumnConfig, ZTableConfig, ZTableControl, ZTableEditCellChangeEvent, ZTableEditConfig, ZTableEditContentConfig, ZTableEditContentType, ZTableEditSize, ZTableEditType, ZTableExcelExportConfig, ZTableExcelExportContext, ZTableExcelExportScope, ZTableFilterChangeEvent, ZTableFilterCondition, ZTableFilterConfig, ZTableFilterJoinOperator, ZTableFilterOperator, ZTableFilterOptionSource, ZTableFilterUi, ZTableFilterValueType, ZTableGroupExpandChange, ZTableGroupExpandEvent, ZTableGroupingConfig, ZTableGroupingMode, ZTablePageChangeEvent, ZTablePaginationConfig, ZTableRowCopyChange, ZTableRowCopyEvent, ZTableRowDeleteChange, ZTableRowDeleteEvent, ZTableRowExpandEvent, ZTableRowInsertChange, ZTableRowInsertEvent, ZTableRowInsertPosition, ZTableRowMoveChange, ZTableRowMoveDirection, ZTableRowMoveEvent, ZTableRowPasteChange, ZTableRowPasteEvent, ZTableRowSelectEvent, ZTableSearchChangeEvent, ZTableSearchConfig, ZTableServerGroup, ZTableSortChangeEvent, ZTableSortConfig, ZTableTagColor };