@sdcorejs/angular 20.1.5 → 20.2.0

package/components/table/index.d.ts

@@ -2,14 +2,14 @@ import * as _angular_core from '@angular/core';
 import { TemplateRef, Signal, InjectionToken, AfterViewInit, OnDestroy } from '@angular/core';
 import { SdBadge } from '@sdcorejs/angular/components/badge';
 import { SdSearch } from '@sdcorejs/angular/forms/models';
-import { Operator, NestedKeyOf, Order, PagingReq, Color } from '@sdcorejs/utils/models';
+import { Operator, NestedKeyOf, Color, Order, PagingReq } from '@sdcorejs/utils/models';
 import { SdUnwrapSignal } from '@sdcorejs/angular/utilities/models';
-import { MatPaginatorIntl, MatPaginator } from '@angular/material/paginator';
+import { MatPaginator, MatPaginatorIntl } from '@angular/material/paginator';
 import { MatSort } from '@angular/material/sort';
 import { MatTable } from '@angular/material/table';
 import { SdExcelColumn } from '@sdcorejs/angular/services';
-import { Observable } from 'rxjs';
 import { SdIconSet } from '@sdcorejs/angular/modules/icon';
+import { Observable } from 'rxjs';
 import { SdButton } from '@sdcorejs/angular/components/button';
 import { CdkDrag, CdkDropList, CdkDragDrop } from '@angular/cdk/drag-drop';
 import { SdQuickAction } from '@sdcorejs/angular/components/quick-action';
@@ -19,8 +19,25 @@ import { SdSideDrawer } from '@sdcorejs/angular/components/side-drawer';
 import { SdModal } from '@sdcorejs/angular/components/modal';
 import { MatSelectionList } from '@angular/material/list';
 
-type SdTableColumn<T = any> = SdTableColumnText<T> | SdTableColumnNumber<T> | SdTableColumnBool<T> | SdTableColumnDate<T> | SdTableColumnValues<T> | SdTableColumnLazyValues<T> | SdTableColumnChildren<T>;
-type SdTableColumnTransformFunc<T = any> = (value: any, rowData: T, args?: {
+type SdTableColumn<T = unknown> = SdTableColumnText<T> | SdTableColumnNumber<T> | SdTableColumnBool<T> | SdTableColumnDate<T> | SdTableColumnValues<T> | SdTableColumnLazyValues<T> | SdTableColumnChildren<T>;
+/**
+ * Cột bảng dùng ở các API **không quan tâm kiểu hàng** — chúng chỉ đọc `field` / `type` / `hidden` /
+ * `filter` và không bao giờ chạm vào dữ liệu hàng (service filter, `SdConvertToPagingReq`, …).
+ *
+ * why: `SdTableColumn<T>` **bất biến (invariant)** theo `T`, vì `T` xuất hiện ở CẢ HAI chiều:
+ * - covariant — `field: NestedKeyOf<T>`;
+ * - contravariant — `transform` / `tooltip` / `click` / `useBadge` / `htmlTemplate` đều nhận `rowData: T`.
+ *
+ * Vì bất biến nên KHÔNG tồn tại siêu kiểu chung: `SdTableColumn<unknown>` hỏng ở chiều contravariant,
+ * `SdTableColumn<never>` hỏng ở chiều covariant (`field` co về `never`). Trước đây default generic là
+ * `any` nên mọi thứ gán được cho nhau — không phải vì kiểu đúng, mà vì `any` tắt kiểm tra hai chiều.
+ *
+ * Public default đã siết sang `unknown` (consumer viết `SdTableColumn<User>` sẽ được suy luận thật và
+ * báo lỗi khi dùng sai). Riêng vài vị trí tham số NỘI BỘ row-agnostic dưới đây vẫn cần một escape
+ * hatch: alias này khoanh vùng `any` vào đúng một chỗ có tài liệu, thay vì rải `any` khắp API công khai.
+ */
+type SdTableColumnAnyRow = SdTableColumn<any>;
+type SdTableColumnTransformFunc<T = unknown> = (value: any, rowData: T, args?: {
     isExport?: boolean;
 }) => string | Promise<string>;
 interface Badge {
@@ -29,8 +46,8 @@ interface Badge {
     icon?: SdUnwrapSignal<SdBadge['icon']>;
     title?: SdUnwrapSignal<SdBadge['title']>;
 }
-type UseBadgeFunc<T = any> = (value: any, rowData: T) => Badge;
-type UseBadgeValuesFunc<T = any, K = any> = (value: any, rowData: T, items: K[]) => Badge;
+type UseBadgeFunc<T = unknown> = (value: any, rowData: T) => Badge;
+type UseBadgeValuesFunc<T = unknown, K = unknown> = (value: any, rowData: T, items: K[]) => Badge;
 interface ColumnTitleOption {
     title: string;
     templateRef?: TemplateRef<any>;
@@ -43,7 +60,7 @@ interface ColumnCellOption {
         type?: 'more' | 'tooltip';
     };
 }
-interface SdTableColumnBase<T = any> {
+interface SdTableColumnBase<T = unknown> {
     title: string | ColumnTitleOption;
     cell?: ColumnCellOption;
     width?: string;
@@ -74,12 +91,12 @@ interface SdTableColumnBase<T = any> {
         description?: string;
     };
 }
-interface SdTableColumnText<T = any> extends SdTableColumnBase<T> {
+interface SdTableColumnText<T = unknown> extends SdTableColumnBase<T> {
     field: NestedKeyOf<T>;
     type: 'string';
     useBadge?: UseBadgeFunc<T>;
 }
-interface SdTableColumnNumber<T = any> extends SdTableColumnBase<T> {
+interface SdTableColumnNumber<T = unknown> extends SdTableColumnBase<T> {
     field: NestedKeyOf<T>;
     type: 'number';
     useBadge?: UseBadgeFunc<T>;
@@ -87,7 +104,7 @@ interface SdTableColumnNumber<T = any> extends SdTableColumnBase<T> {
         type?: 'split-number';
     };
 }
-interface SdTableColumnBool<T = any> extends SdTableColumnBase<T> {
+interface SdTableColumnBool<T = unknown> extends SdTableColumnBase<T> {
     field: NestedKeyOf<T>;
     type: 'boolean';
     useBadge?: UseBadgeFunc<T>;
@@ -96,7 +113,7 @@ interface SdTableColumnBool<T = any> extends SdTableColumnBase<T> {
         displayOnFalse?: string;
     };
 }
-interface SdTableColumnDate<T = any> extends SdTableColumnBase<T> {
+interface SdTableColumnDate<T = unknown> extends SdTableColumnBase<T> {
     field: NestedKeyOf<T>;
     type: 'date' | 'datetime' | 'time';
     useBadge?: UseBadgeFunc<T>;
@@ -104,7 +121,7 @@ interface SdTableColumnDate<T = any> extends SdTableColumnBase<T> {
         type?: 'daterange' | 'date' | 'split-date';
     };
 }
-interface SdTableColumnValues<T = any, K = Record<string, any>> extends SdTableColumnBase<T> {
+interface SdTableColumnValues<T = unknown, K = Record<string, any>> extends SdTableColumnBase<T> {
     field: NestedKeyOf<T>;
     type: 'values';
     useBadge?: UseBadgeValuesFunc<T, K>;
@@ -115,7 +132,7 @@ interface SdTableColumnValues<T = any, K = Record<string, any>> extends SdTableC
         selection?: 'MULTIPLE';
     };
 }
-interface SdTableColumnLazyValues<T = any, K = Record<string, any>> extends SdTableColumnBase<T> {
+interface SdTableColumnLazyValues<T = unknown, K = Record<string, any>> extends SdTableColumnBase<T> {
     field: NestedKeyOf<T>;
     type: 'lazy-values';
     useBadge?: UseBadgeFunc<T>;
@@ -127,8 +144,8 @@ interface SdTableColumnLazyValues<T = any, K = Record<string, any>> extends SdTa
         selection?: 'MULTIPLE';
     };
 }
-type SdTableColumnNormal<T = any> = Exclude<SdTableColumn<T>, SdTableColumnChildren<T>>;
-interface SdTableColumnChildren<T = any> extends SdTableColumnBase<T> {
+type SdTableColumnNormal<T = unknown> = Exclude<SdTableColumn<T>, SdTableColumnChildren<T>>;
+interface SdTableColumnChildren<T = unknown> extends SdTableColumnBase<T> {
     field: string;
     type: 'children';
     children: SdTableColumnNormal<T>[];
@@ -147,6 +164,71 @@ declare class SdTableCellDefDirective<T = any> {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SdTableCellDefDirective<any>, "[sdTableCellDef]", never, { "sdTableCellDef": { "alias": "sdTableCellDef"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * Nội dung cho ô HEADER của cột command.
+ *
+ * Ô đó vốn để trống — chỉ giữ chỗ cho các nút thao tác bên dưới — nên đây là chỗ tự nhiên để đặt
+ * một hành động cấp bảng (thường là "thêm dòng") mà không tốn thêm một dải riêng dưới bảng.
+ *
+ * Không có input: cột command chỉ có một, khác `sdTableCellDef` / `sdTableTitleDef` vốn phải chỉ
+ * đích danh field.
+ *
+ * ```html
+ * <sd-table [option]="option">
+ *   <ng-template sdTableCommandHeaderDef>
+ *     <sd-button prefixIcon="add" type="text" (click)="addRow()"></sd-button>
+ *   </ng-template>
+ * </sd-table>
+ * ```
+ */
+declare class SdTableCommandHeaderDefDirective {
+    templateRef: TemplateRef<unknown>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdTableCommandHeaderDefDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SdTableCommandHeaderDefDirective, "[sdTableCommandHeaderDef]", never, {}, {}, never, never, true, never>;
+}
+
+interface SdTableGroupDefContext<T = any> {
+    /** Children items thuộc group hiện tại (kèm wrapper SdTableItem). */
+    items: SdTableItem<T>[];
+    /** Children raw data (đã unwrap khỏi SdTableItem) — tiện dùng trong template. */
+    data: T[];
+    /** Hash key của group (Utilities.hash(values)). */
+    key: string;
+    /** Resolved giá trị các field group — vd `{ customerId: 1, customerName: 'A' }`. */
+    values: Record<string, any>;
+    /** true nếu group đang expand, false nếu collapse (chỉ ý nghĩa khi option.group.collapsible). */
+    isExpanded: boolean;
+    /** true nếu mọi children selectable đều selected. */
+    isSelected: boolean;
+    /** true nếu một phần children selected (partial). */
+    indeterminate: boolean;
+    /** Toggle expand/collapse (chỉ chạy nếu collapsible). */
+    toggleExpand: () => void;
+    /** Toggle select-all cho cả group (chỉ chạy nếu selector visible). */
+    toggleSelect: () => void;
+}
+/**
+ * Directive cung cấp custom template render group header row trong sd-table.
+ * Thay thế cho htmlTemplate callback cũ — cho phép Angular template binding,
+ * pipes, components con (sd-badge, sd-button, …) bên trong.
+ *
+ * Ví dụ:
+ * ```html
+ * <sd-table [option]="opt">
+ *   <ng-template sdTableGroupDef let-values="values" let-items="items" let-indeterminate="indeterminate">
+ *     <b>Khách hàng: {{ values.customerName }}</b>
+ *     <span>{{ items.length }} đơn hàng</span>
+ *   </ng-template>
+ * </sd-table>
+ * ```
+ */
+declare class SdTableGroupDefDirective<T = any> {
+    static ngTemplateContextGuard<T>(_dir: SdTableGroupDefDirective<T>, _ctx: unknown): _ctx is SdTableGroupDefContext<T>;
+    templateRef: TemplateRef<SdTableGroupDefContext<T>>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdTableGroupDefDirective<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SdTableGroupDefDirective<any>, "[sdTableGroupDef]", never, {}, {}, never, never, true, never>;
+}
+
 interface SdTableMetaSelector {
     selectable?: boolean;
     isSelected?: boolean;
@@ -188,6 +270,12 @@ interface SdTableDisplay {
 interface SdTableMetaGroup<T = any> {
     /** Children items thuộc group này (chỉ set trên group header row). */
     items?: SdTableItem<T>[];
+    /**
+     * Raw data của children (`items.map(i => i.data)`).
+     * why: precompute 1 lần lúc SdGroupPipe dựng header — trước đây `groupContext()`
+     * map lại mảng này ở MỖI change-detection pass cho MỖI group row.
+     */
+    data?: T[];
     /** true = row này là synthetic group header (sinh bởi SdGroupPipe). */
     isGroupHeader?: boolean;
     /** Hash key của group (= Utilities.hash(values)). */
@@ -196,6 +284,20 @@ interface SdTableMetaGroup<T = any> {
     values?: Record<string, any>;
     /** Trạng thái expand. Chỉ ý nghĩa khi `option.group.collapsible = true`. */
     isExpanded?: boolean;
+    /**
+     * true nếu MỌI selectable child trong group đã được chọn.
+     * why: cache thay cho `isGroupAllSelected(item)` gọi trong template — hàm đó duyệt
+     * toàn bộ children mỗi CD pass. Cập nhật ở selection sync path (`#updateSelectedItems`).
+     */
+    isSelected?: boolean;
+    /** true nếu chỉ MỘT PHẦN children được chọn (partial). Cache — xem `isSelected`. */
+    indeterminate?: boolean;
+    /**
+     * Context ổn định truyền cho template `sdTableGroupDef`.
+     * why: giữ NGUYÊN reference qua các CD pass để `ngTemplateOutlet` không phải
+     * dựng lại embedded view; giá trị bên trong được mutate tại chỗ khi selection đổi.
+     */
+    context?: SdTableGroupDefContext<T>;
 }
 interface SdTableMeta<T> {
     id: string;
@@ -204,6 +306,12 @@ interface SdTableMeta<T> {
     expand?: SdTableMetaExpand;
     group?: SdTableMetaGroup<T>;
     tree?: SdTableMetaTree<T>;
+    /**
+     * Style inline của cả row, resolve từ `option.style.rowCss` MỘT LẦN mỗi lần render.
+     * why: template bind `[ngStyle]` trực tiếp vào đây; gọi `rowCss(...)` trong binding
+     * trả object MỚI mỗi CD pass → KeyValueDiffer phải diff lại toàn bộ row mỗi pass.
+     */
+    rowStyle?: Record<string, string> | null;
 }
 interface SdTableItem<T = any> {
     meta: SdTableMeta<T>;
@@ -244,48 +352,6 @@ declare class SdMaterialFooterDefDirective<T = any> {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SdMaterialFooterDefDirective<any>, "[sdTableFooterDef]", never, { "sdTableFooterDef": { "alias": "sdTableFooterDef"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-interface SdTableGroupDefContext<T = any> {
-    /** Children items thuộc group hiện tại (kèm wrapper SdTableItem). */
-    items: SdTableItem<T>[];
-    /** Children raw data (đã unwrap khỏi SdTableItem) — tiện dùng trong template. */
-    data: T[];
-    /** Hash key của group (Utilities.hash(values)). */
-    key: string;
-    /** Resolved giá trị các field group — vd `{ customerId: 1, customerName: 'A' }`. */
-    values: Record<string, any>;
-    /** true nếu group đang expand, false nếu collapse (chỉ ý nghĩa khi option.group.collapsible). */
-    isExpanded: boolean;
-    /** true nếu mọi children selectable đều selected. */
-    isSelected: boolean;
-    /** true nếu một phần children selected (partial). */
-    indeterminate: boolean;
-    /** Toggle expand/collapse (chỉ chạy nếu collapsible). */
-    toggleExpand: () => void;
-    /** Toggle select-all cho cả group (chỉ chạy nếu selector visible). */
-    toggleSelect: () => void;
-}
-/**
- * Directive cung cấp custom template render group header row trong sd-table.
- * Thay thế cho htmlTemplate callback cũ — cho phép Angular template binding,
- * pipes, components con (sd-badge, sd-button, …) bên trong.
- *
- * Ví dụ:
- * ```html
- * <sd-table [option]="opt">
- *   <ng-template sdTableGroupDef let-values="values" let-items="items" let-indeterminate="indeterminate">
- *     <b>Khách hàng: {{ values.customerName }}</b>
- *     <span>{{ items.length }} đơn hàng</span>
- *   </ng-template>
- * </sd-table>
- * ```
- */
-declare class SdTableGroupDefDirective<T = any> {
-    static ngTemplateContextGuard<T>(_dir: SdTableGroupDefDirective<T>, _ctx: unknown): _ctx is SdTableGroupDefContext<T>;
-    templateRef: TemplateRef<SdTableGroupDefContext<T>>;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdTableGroupDefDirective<any>, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SdTableGroupDefDirective<any>, "[sdTableGroupDef]", never, {}, {}, never, never, true, never>;
-}
-
 interface Context<T = any> {
     column: SdTableColumn<T>;
 }
@@ -297,6 +363,30 @@ declare class SdTableTitleDefDirective<T = any> {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SdTableTitleDefDirective<any>, "[sdTableTitleDef]", never, { "sdTableTitleDef": { "alias": "sdTableTitleDef"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+interface SdTableCommandOption<T = any> {
+    align?: 'left' | 'right';
+    commands?: SdTableCommand<T>[];
+}
+type SdTableCommand<T = any> = SdTableCommandNormal<T> | SdTableCommandChildren<T>;
+interface SdTableCommandNormal<T = any> {
+    color?: Color;
+    icon?: string | ((rowData: T) => string);
+    fontSet?: SdIconSet;
+    title?: string | ((rowData: T) => string);
+    disabled?: boolean | ((rowData: T) => boolean);
+    hidden?: boolean | ((rowData: T) => boolean | Promise<boolean>);
+    click: (rowData: T) => void;
+    htmlTemplate?: (rowData: T) => string;
+}
+interface SdTableCommandChildren<T = any> {
+    icon?: string | ((rowData: T) => string);
+    fontSet?: SdIconSet;
+    title?: string | ((rowData: T) => string);
+    disabled?: boolean | ((rowData: T) => boolean);
+    hidden?: boolean | ((rowData: T) => boolean | Promise<boolean>);
+    children: SdTableCommandNormal<T>[];
+}
+
 interface SdTableQuickFilter {
     code: string;
     columnFilter: Record<string, any>;
@@ -312,7 +402,7 @@ interface TableFilterValue {
     notReload?: boolean;
     filtered?: boolean;
 }
-interface SdTableFilterRequest<T = any> {
+interface SdTableFilterRequest<T = unknown> {
     columnOperator: Record<NestedKeyOf<T>, Operator>;
     rawColumnFilter: Record<NestedKeyOf<T>, any>;
     rawExternalFilter: Record<string, any>;
@@ -323,7 +413,7 @@ interface SdTableFilterRequest<T = any> {
     isExported?: boolean;
     visibledColumns?: SdTableColumn[];
 }
-interface SdTableOptionFilter<T = any> {
+interface SdTableOptionFilter<T = unknown> {
     /** Key định danh nếu muốn lưu cache */
     key?: string;
     /** Có bật cache giá trị filter hay không */
@@ -348,13 +438,13 @@ interface SdTableOptionFilter<T = any> {
     onClearFilter?: () => void;
 }
 declare const SdConvertToPagingReq: (filterRequest: SdTableFilterRequest, args: {
-    columns?: SdTableColumn[];
+    columns?: SdTableColumnAnyRow[];
     externalFilters?: SdTableExternalFilter[];
     fieldMapping?: Record<string, string>;
     orders?: Order[];
 }) => PagingReq;
-declare type SdTableExternalFilter<TData = any> = TextFilter<TData> | DateFilter<TData> | DateTimeFilter<TData> | DateRangeFilter<TData> | NumberFilter<TData> | ValuesFilter<TData> | LazyValuesFilter<TData> | BooleanFilter<TData> | CustomFilter<TData>;
-interface BaseFilter<TData = any> {
+declare type SdTableExternalFilter<TData = unknown> = TextFilter<TData> | DateFilter<TData> | DateTimeFilter<TData> | DateRangeFilter<TData> | NumberFilter<TData> | ValuesFilter<TData> | LazyValuesFilter<TData> | BooleanFilter<TData> | CustomFilter<TData>;
+interface BaseFilter<TData = unknown> {
     field: string;
     title: string;
     defaultShowing?: boolean;
@@ -364,23 +454,23 @@ interface BaseFilter<TData = any> {
     data?: TData;
     onChange?: (value: any) => void;
 }
-interface TextFilter<TData = any> extends BaseFilter<TData> {
+interface TextFilter<TData = unknown> extends BaseFilter<TData> {
     type: 'string';
     default?: string;
 }
-interface DateFilter<TData = any> extends BaseFilter<TData> {
+interface DateFilter<TData = unknown> extends BaseFilter<TData> {
     type: 'date';
     default?: Date | string;
     minDate?: string | number | Date;
     maxDate?: string | number | Date;
 }
-interface DateTimeFilter<TData = any> extends BaseFilter<TData> {
+interface DateTimeFilter<TData = unknown> extends BaseFilter<TData> {
     type: 'datetime';
     default?: Date | string;
     minDate?: string | number | Date;
     maxDate?: string | number | Date;
 }
-interface DateRangeFilter<TData = any> extends BaseFilter<TData> {
+interface DateRangeFilter<TData = unknown> extends BaseFilter<TData> {
     type: 'daterange';
     enableTime?: boolean;
     minDate?: string | number | Date;
@@ -390,11 +480,11 @@ interface DateRangeFilter<TData = any> extends BaseFilter<TData> {
         to?: Date | string;
     };
 }
-interface NumberFilter<TData = any> extends BaseFilter<TData> {
+interface NumberFilter<TData = unknown> extends BaseFilter<TData> {
     type: 'number';
     default?: number;
 }
-interface ValuesFilter<TData = any> extends BaseFilter<TData> {
+interface ValuesFilter<TData = unknown> extends BaseFilter<TData> {
     type: 'values';
     option: {
         valueField: string;
@@ -404,7 +494,7 @@ interface ValuesFilter<TData = any> extends BaseFilter<TData> {
     };
     default?: string | string[];
 }
-interface LazyValuesFilter<TData = any> extends BaseFilter<TData> {
+interface LazyValuesFilter<TData = unknown> extends BaseFilter<TData> {
     type: 'lazy-values';
     option: {
         valueField: string;
@@ -414,7 +504,7 @@ interface LazyValuesFilter<TData = any> extends BaseFilter<TData> {
     };
     default?: string | string[];
 }
-interface BooleanFilter<TData = any> extends BaseFilter<TData> {
+interface BooleanFilter<TData = unknown> extends BaseFilter<TData> {
     type: 'boolean';
     option?: {
         displayOnTrue?: string;
@@ -422,7 +512,7 @@ interface BooleanFilter<TData = any> extends BaseFilter<TData> {
     };
     default?: boolean;
 }
-interface CustomFilter<TData = any> extends BaseFilter<TData> {
+interface CustomFilter<TData = unknown> extends BaseFilter<TData> {
     type: 'custom';
     filterDef?: TemplateRef<any>;
     default?: any;
@@ -442,30 +532,6 @@ interface TableFilterRegister {
     };
 }
 
-interface SdTableCommandOption<T = any> {
-    align?: 'left' | 'right';
-    commands?: SdTableCommand<T>[];
-}
-type SdTableCommand<T = any> = SdTableCommandNormal<T> | SdTableCommandChildren<T>;
-interface SdTableCommandNormal<T = any> {
-    color?: Color;
-    icon?: string | ((rowData: T) => string);
-    fontSet?: SdIconSet;
-    title?: string | ((rowData: T) => string);
-    disabled?: boolean | ((rowData: T) => boolean);
-    hidden?: boolean | ((rowData: T) => boolean | Promise<boolean>);
-    click: (rowData: T) => void;
-    htmlTemplate?: (rowData: T) => string;
-}
-interface SdTableCommandChildren<T = any> {
-    icon?: string | ((rowData: T) => string);
-    fontSet?: SdIconSet;
-    title?: string | ((rowData: T) => string);
-    disabled?: boolean | ((rowData: T) => boolean);
-    hidden?: boolean | ((rowData: T) => boolean | Promise<boolean>);
-    children: SdTableCommandNormal<T>[];
-}
-
 interface TableOptionConfig {
     visible?: boolean;
     resizable?: boolean;
@@ -619,14 +685,15 @@ interface SdTableOptionSelector<T = any> {
      *
      * - Default (false): selection bị mất khi data items được re-fetch (server-side) hoặc
      *   item references thay đổi. Action bar chỉ hiển thị số item selected ở page hiện tại.
-     * - Enabled (true): table giữ map nội bộ selectedItems theo `meta.id` (hash của data).
+     * - Enabled (true): table giữ map nội bộ selectedItems theo `meta.id`.
      *   Sau mỗi #render, restore `isSelected` cho item nào id đã có trong map.
      *   `selectedTableItems()` trả về TOÀN BỘ item đã chọn xuyên trang (kể cả off-page),
      *   nên action bar + callback `click(items)` nhận đầy đủ data đang được chọn.
      *
-     * Lưu ý: matching dựa trên `Utilities.hash(data)` — hai item có cùng data shape sẽ
-     * trùng id (mong muốn). Nếu data có timestamp/random field thay đổi giữa các lần fetch,
-     * id sẽ khác và selection không restore được.
+     * ⚠️ Matching dựa trên `meta.id`. Không khai báo `option.rowKey` thì id được sinh theo
+     * IDENTITY của object data — sống qua filter/sort/paging phía client, nhưng KHÔNG sống
+     * qua một lần fetch mới của server (object mới → id mới). Với `type: 'server'`, HÃY
+     * khai báo `option.rowKey` trỏ vào field định danh của dòng.
      */
     preserveSelection?: boolean;
 }
@@ -819,6 +886,18 @@ interface SdTableBaseOption<T = any> {
      * ví dụ các option có hỗ trợ cache/config theo key.
      */
     key?: string;
+    /**
+     * Field định danh của MỘT DÒNG (hỗ trợ dot-notation, vd `'id'` hoặc `'user.id'`).
+     *
+     * Table dùng giá trị này làm `SdTableItem.meta.id` — khoá cho `trackBy` của mat-table,
+     * cho `preserveSelection`, cho trạng thái bung của tree và cho các `data-autoid` theo dòng.
+     *
+     * Không truyền thì table tự sinh id theo IDENTITY của object data (ổn định trong suốt
+     * vòng đời object, nhưng KHÔNG sống sót qua một lần fetch mới của server). Vì vậy hãy
+     * khai báo `rowKey` khi dùng `preserveSelection`, `tree` với `type: 'server'`, hoặc khi
+     * cần autoId theo dòng ổn định cho E2E.
+     */
+    rowKey?: string;
     /**
      * Cấu hình hiển thị/phục hồi config của table.
      * Xem thêm kiểu chi tiết tại `TableOptionConfig`.
@@ -981,7 +1060,7 @@ interface SdTableServerOption<T = any> extends SdTableBaseOption<T> {
 declare class ExternalFilterComponent {
     #private;
     autoIdInput: _angular_core.InputSignal<string | null | undefined>;
-    filter: _angular_core.InputSignal<SdTableOptionFilter<any> | undefined>;
+    filter: _angular_core.InputSignal<SdTableOptionFilter<unknown> | undefined>;
     externalFilters: _angular_core.InputSignal<SdTableExternalFilter[] | null | undefined>;
     filterRegister: _angular_core.InputSignal<TableFilterRegister | undefined>;
     externalFilter: _angular_core.WritableSignal<Record<string, any>>;
@@ -1018,7 +1097,7 @@ declare class ExternalFilterComponent {
  */
 declare class MobileFilterComponent {
     autoIdInput: _angular_core.InputSignal<string | null | undefined>;
-    filter: _angular_core.InputSignal<SdTableOptionFilter<any> | undefined>;
+    filter: _angular_core.InputSignal<SdTableOptionFilter<unknown> | undefined>;
     externalFilters: _angular_core.InputSignal<SdTableExternalFilter[] | null | undefined>;
     columns: _angular_core.InputSignal<SdTableColumn[] | null | undefined>;
     filterDefs: _angular_core.InputSignal<readonly SdTableFilterDefDirective[] | null | undefined>;
@@ -1055,6 +1134,11 @@ declare class ConfigComponent {
     close: () => void;
     onSave: () => void;
     onReset: () => Promise<void>;
+    /**
+     * Cột đang tắt hiển thị thì tiêu đề / độ rộng / cố định / giới hạn ký tự đều vô nghĩa —
+     * khoá chúng lại để row nói rõ trạng thái, chỉ chừa ô "Hiển thị" để bật lại.
+     */
+    isRowDisabled: (item: ConfiguredColumn) => boolean;
     dropTable(event: any): void;
     handleMouseDown(): void;
     handleMouseUp(): void;
@@ -1136,7 +1220,22 @@ interface ISdTableConfiguration {
 }
 declare const SD_TABLE_CONFIGURATION: InjectionToken<ISdTableConfiguration>;
 
-declare class MatPaginatorIntlCro extends MatPaginatorIntl {
+/**
+ * Cầu nối giữa `SdGroupPipe` (nơi group header được sinh ra) và `SdTable`.
+ *
+ * why: pipe dựng header nhưng KHÔNG biết method của component, còn component thì không
+ * giữ mảng output của pipe. Host là một object DUY NHẤT, ổn định do component sở hữu:
+ * pipe đổ header vào `headers` để component sync lại selection state sau này, và mượn
+ * `toggleExpand`/`toggleSelect` để gắn vào template context.
+ */
+interface SdGroupHeaderHost<T = any> {
+    /** Sink các group header của lần transform gần nhất. Pipe clear + fill lại mỗi lần. */
+    headers: SdTableItem<T>[];
+    toggleExpand: (header: SdTableItem<T>) => void;
+    toggleSelect: (header: SdTableItem<T>) => void;
+}
+
+declare class SdTablePaginatorIntl extends MatPaginatorIntl {
     #private;
     firstPageLabel: string;
     lastPageLabel: string;
@@ -1144,8 +1243,8 @@ declare class MatPaginatorIntlCro extends MatPaginatorIntl {
     nextPageLabel: string;
     previousPageLabel: string;
     getRangeLabel: (page: number, pageSize: number, length: number) => string;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MatPaginatorIntlCro, never>;
-    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MatPaginatorIntlCro>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdTablePaginatorIntl, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<SdTablePaginatorIntl>;
 }
 declare class SdTable<T = unknown> implements AfterViewInit, OnDestroy {
     #private;
@@ -1164,6 +1263,8 @@ declare class SdTable<T = unknown> implements AfterViewInit, OnDestroy {
     sdSubInformation: _angular_core.Signal<SdTableExpandDefDirective<any> | undefined>;
     sdGroupDef: _angular_core.Signal<SdTableGroupDefDirective<any> | undefined>;
     sdCellDefs: _angular_core.Signal<readonly SdTableCellDefDirective<any>[]>;
+    /** Nội dung tuỳ chọn cho ô header của cột command (mặc định ô này để trống). */
+    sdCommandHeaderDef: _angular_core.Signal<SdTableCommandHeaderDefDirective | undefined>;
     sdFooterDefs: _angular_core.Signal<readonly SdMaterialFooterDefDirective<any>[]>;
     sdFilterDefs: _angular_core.Signal<readonly SdTableFilterDefDirective[]>;
     sdTitleDefs: _angular_core.Signal<readonly SdTableTitleDefDirective<any>[]>;
@@ -1178,6 +1279,25 @@ declare class SdTable<T = unknown> implements AfterViewInit, OnDestroy {
     total: _angular_core.WritableSignal<number | undefined>;
     loading: _angular_core.WritableSignal<boolean>;
     isSelectAll: _angular_core.WritableSignal<boolean>;
+    /**
+     * Checkbox "chọn tất cả" ở header có hiển thị không.
+     *
+     * why: trước đây là `_items | selectionVisibleSelectAll: … | async` — pipe `async`
+     * với `await setTimeout(500)` bên trong. Sleep đó CHE một vấn đề thứ tự
+     * change-detection: pipe đọc `meta.selector.actions`, mảng chỉ được `SdSelectionVisiblePipe`
+     * ghi khi cell BODY render, mà CDK dựng header TRƯỚC body → pass đầu luôn đọc ra rỗng.
+     * Hệ quả: checkbox hiện trễ 500ms, và vì `transform` là `async` nên MỖI lần re-eval lại
+     * trả một Promise mới + đặt thêm một timer không ai dọn. Computed tự tính từ
+     * `items()` + `selector` nên không phụ thuộc pipe nào chạy trước → bỏ hẳn timer.
+     */
+    visibleSelectAll: _angular_core.Signal<boolean>;
+    /**
+     * Danh sách command của row, memoize theo option.
+     * why: template cũ bind `_tableOption.command?.commands || _tableOption.commands || []`
+     * — nhánh `[]` cấp phát mảng MỚI mỗi CD pass và đẩy vào `input()` của `desktop-command`,
+     * làm child OnPush bị đánh dấu dirty mỗi pass cho từng dòng.
+     */
+    rowCommands: _angular_core.Signal<SdTableCommand<T>[]>;
     isFiltered: _angular_core.WritableSignal<boolean>;
     requireFiltered: _angular_core.WritableSignal<boolean>;
     filterRegister: TableFilterRegister;
@@ -1187,7 +1307,7 @@ declare class SdTable<T = unknown> implements AfterViewInit, OnDestroy {
     cacheValues: Record<string, unknown[]>;
     treeRevision: _angular_core.WritableSignal<number>;
     exporting: _angular_core.WritableSignal<boolean>;
-    exportTitle: _angular_core.WritableSignal<string>;
+    exportTitle: _angular_core.Signal<string>;
     tableConfiguration: ISdTableConfiguration | null;
     constructor();
     ngAfterViewInit(): void;
@@ -1211,6 +1331,14 @@ declare class SdTable<T = unknown> implements AfterViewInit, OnDestroy {
     /** Toggle select-all cho 1 group: set isSelected cho mọi selectable child, sync state. */
     onSelectGroup: (header: SdTableItem<T>, checked: boolean) => void;
     groupExpandState: Map<string, boolean>;
+    /**
+     * Cầu nối tới SdGroupPipe (arg 4) — object DUY NHẤT, tạo một lần.
+     * why: pipe sinh group header nhưng component mới là nơi biết selection đổi. Pipe đổ
+     * header vào `headers` để `#syncGroupSelectionState` cập nhật `meta.group.isSelected` /
+     * `indeterminate`, thay cho việc template gọi `isGroupAllSelected()`/`isGroupIndeterminate()`
+     * (duyệt toàn bộ children) ở MỖI CD pass.
+     */
+    readonly groupHost: SdGroupHeaderHost<T>;
     /** Toggle expand/collapse cho 1 group (chỉ ý nghĩa khi option.group.collapsible). */
     toggleGroupExpand: (header: SdTableItem<T>) => void;
     /**
@@ -1225,7 +1353,21 @@ declare class SdTable<T = unknown> implements AfterViewInit, OnDestroy {
      * Span TOÀN BỘ width data row vì group row chỉ có 1 cell.
      */
     sdGroupColspan: _angular_core.Signal<number>;
-    /** Build context object truyền vào SdTableGroupDefDirective template. */
+    /**
+     * Context truyền vào template `sdTableGroupDef`.
+     *
+     * why: bản cũ dựng object MỚI (kèm `items.map(i => i.data)` mới và 2 lần duyệt children
+     * qua `isGroupAllSelected`/`isGroupIndeterminate`) ở MỖI CD pass, cho MỖI group row —
+     * `ngTemplateOutlet` thấy context đổi reference nên phải dựng lại embedded view. Giờ
+     * context được `SdGroupPipe` precompute và cache trên `meta.group`; ở đây chỉ đọc ra
+     * (fallback `??=` cho header không do pipe sinh) nên reference ổn định qua các pass.
+     *
+     * why: 3 field selection/expand thì phải làm TƯƠI mỗi lần đọc — `SdGroupPipe` dựng context
+     * lúc header được sinh ra, thời điểm đó `selector.selectable` của children vẫn còn là mặc
+     * định `false` (chỉ `SdSelectionVisiblePipe` ở cell BODY mới đặt đúng, mà CDK dựng header
+     * trước body). Cache lại giá trị tính ở thời điểm đó là khoá cứng `isSelected = false`.
+     * Mutate TẠI CHỖ để `ngTemplateOutlet` vẫn thấy cùng một reference và không dựng lại view.
+     */
     groupContext: (header: SdTableItem<T>) => SdTableGroupDefContext<T>;
     rowStyle: (row: SdTableItem<T>, index?: number) => Record<string, string> | null;
     clearFilter: () => void;
@@ -1241,8 +1383,8 @@ declare class SdTable<T = unknown> implements AfterViewInit, OnDestroy {
     reorderSortPredicate: (index: number, drag: CdkDrag<SdTableItem<T>>, drop: CdkDropList<SdTableItem<T>[]>) => boolean;
     onReorderDrop(event: CdkDragDrop<SdTableItem<T>[]>): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdTable<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdTable<any>, "sd-table", never, { "autoIdInput": { "alias": "autoId"; "required": false; "isSignal": true; }; "option": { "alias": "option"; "required": true; "isSignal": true; }; }, {}, ["sdSubInformation", "sdGroupDef", "sdCellDefs", "sdFooterDefs", "sdFilterDefs", "sdTitleDefs"], ["[sdTableTop]"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdTable<any>, "sd-table", never, { "autoIdInput": { "alias": "autoId"; "required": false; "isSignal": true; }; "option": { "alias": "option"; "required": true; "isSignal": true; }; }, {}, ["sdSubInformation", "sdGroupDef", "sdCellDefs", "sdCommandHeaderDef", "sdFooterDefs", "sdFilterDefs", "sdTitleDefs"], ["[sdTableTop]"], true, never>;
 }
 
-export { MatPaginatorIntlCro, SD_TABLE_CONFIGURATION, SdConvertToPagingReq, SdMaterialFooterDefDirective, SdTable, SdTableCellDefDirective, SdTableExpandDefDirective, SdTableFilterDefDirective, SdTableGroupDefDirective, SdTableTitleDefDirective };
-export type { ISdTableConfiguration, SdTableColumn, SdTableColumnChildren, SdTableColumnLazyValues, SdTableColumnNormal, SdTableColumnTransformFunc, SdTableColumnValues, SdTableCommand, SdTableCommandChildren, SdTableCommandNormal, SdTableCommandOption, SdTableDisplay, SdTableExternalFilter, SdTableFilterRequest, SdTableGroupDefContext, SdTableItem, SdTableMeta, SdTableOption, SdTableOptionFilter, SdTableOptionTree, SdTableQuickFilter, TableFilterConfiguration, TableFilterRegister, TableFilterValue, TableOptionTreeLazy, TableOptionTreeStatic };
+export { SD_TABLE_CONFIGURATION, SdConvertToPagingReq, SdMaterialFooterDefDirective, SdTable, SdTableCellDefDirective, SdTableCommandHeaderDefDirective, SdTableExpandDefDirective, SdTableFilterDefDirective, SdTableGroupDefDirective, SdTablePaginatorIntl, SdTableTitleDefDirective };
+export type { ISdTableConfiguration, SdTableColumn, SdTableColumnAnyRow, SdTableColumnChildren, SdTableColumnLazyValues, SdTableColumnNormal, SdTableColumnTransformFunc, SdTableColumnValues, SdTableCommand, SdTableCommandChildren, SdTableCommandNormal, SdTableCommandOption, SdTableDisplay, SdTableExternalFilter, SdTableFilterRequest, SdTableGroupDefContext, SdTableItem, SdTableMeta, SdTableOption, SdTableOptionFilter, SdTableOptionTree, SdTableQuickFilter, TableFilterConfiguration, TableFilterRegister, TableFilterValue, TableOptionTreeLazy, TableOptionTreeStatic };