@sdcorejs/angular 19.1.6 → 19.2.0

package/components/table/src/models/table-column.model.d.ts

@@ -3,8 +3,25 @@ import { SdBadge } from '@sdcorejs/angular/components/badge';
 import type { SdSearch } from '@sdcorejs/angular/forms/models';
 import { NestedKeyOf, Operator } from '@sdcorejs/utils/models';
 import { SdUnwrapSignal } from '@sdcorejs/angular/utilities/models';
-export type SdTableColumn<T = any> = SdTableColumnText<T> | SdTableColumnNumber<T> | SdTableColumnBool<T> | SdTableColumnDate<T> | SdTableColumnValues<T> | SdTableColumnLazyValues<T> | SdTableColumnChildren<T>;
-export type SdTableColumnTransformFunc<T = any> = (value: any, rowData: T, args?: {
+export 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.
+ */
+export type SdTableColumnAnyRow = SdTableColumn<any>;
+export type SdTableColumnTransformFunc<T = unknown> = (value: any, rowData: T, args?: {
     isExport?: boolean;
 }) => string | Promise<string>;
 interface Badge {
@@ -13,8 +30,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>;
@@ -27,7 +44,7 @@ interface ColumnCellOption {
         type?: 'more' | 'tooltip';
     };
 }
-interface SdTableColumnBase<T = any> {
+interface SdTableColumnBase<T = unknown> {
     title: string | ColumnTitleOption;
     cell?: ColumnCellOption;
     width?: string;
@@ -58,12 +75,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>;
@@ -71,7 +88,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>;
@@ -80,7 +97,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>;
@@ -88,7 +105,7 @@ interface SdTableColumnDate<T = any> extends SdTableColumnBase<T> {
         type?: 'daterange' | 'date' | 'split-date';
     };
 }
-export interface SdTableColumnValues<T = any, K = Record<string, any>> extends SdTableColumnBase<T> {
+export interface SdTableColumnValues<T = unknown, K = Record<string, any>> extends SdTableColumnBase<T> {
     field: NestedKeyOf<T>;
     type: 'values';
     useBadge?: UseBadgeValuesFunc<T, K>;
@@ -99,7 +116,7 @@ export interface SdTableColumnValues<T = any, K = Record<string, any>> extends S
         selection?: 'MULTIPLE';
     };
 }
-export interface SdTableColumnLazyValues<T = any, K = Record<string, any>> extends SdTableColumnBase<T> {
+export interface SdTableColumnLazyValues<T = unknown, K = Record<string, any>> extends SdTableColumnBase<T> {
     field: NestedKeyOf<T>;
     type: 'lazy-values';
     useBadge?: UseBadgeFunc<T>;
@@ -111,8 +128,8 @@ export interface SdTableColumnLazyValues<T = any, K = Record<string, any>> exten
         selection?: 'MULTIPLE';
     };
 }
-export type SdTableColumnNormal<T = any> = Exclude<SdTableColumn<T>, SdTableColumnChildren<T>>;
-export interface SdTableColumnChildren<T = any> extends SdTableColumnBase<T> {
+export type SdTableColumnNormal<T = unknown> = Exclude<SdTableColumn<T>, SdTableColumnChildren<T>>;
+export interface SdTableColumnChildren<T = unknown> extends SdTableColumnBase<T> {
     field: string;
     type: 'children';
     children: SdTableColumnNormal<T>[];

package/components/table/src/models/table-item.model.d.ts

@@ -1,5 +1,6 @@
 import { SdBadge } from '@sdcorejs/angular/components/badge';
 import { SdUnwrapSignal } from '@sdcorejs/angular/utilities/models';
+import type { SdTableGroupDefContext } from '../directives/sd-table-group-def.directive';
 export interface SdTableMetaSelector {
     selectable?: boolean;
     isSelected?: boolean;
@@ -41,6 +42,12 @@ export interface SdTableDisplay {
 export 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)). */
@@ -49,6 +56,20 @@ export 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>;
 }
 export interface SdTableMeta<T> {
     id: string;
@@ -57,9 +78,17 @@ export 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;
 }
 export interface SdTableItem<T = any> {
     meta: SdTableMeta<T>;
     data: T;
 }
-export declare const MapToSdTableItem: <T = any>(item: T) => SdTableItem<T>;
+/** Resolve id cho một row data. Xem chú thích ở `rowIdByData` để biết thứ tự ưu tiên. */
+export declare const resolveTableItemId: <T = any>(item: T, rowKey?: string) => string;
+export declare const MapToSdTableItem: <T = any>(item: T, rowKey?: string) => SdTableItem<T>;

package/components/table/src/models/table-option-selector.model.d.ts

@@ -27,14 +27,15 @@ export 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;
 }

package/components/table/src/models/table-option.model.d.ts

@@ -20,6 +20,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`.

package/components/table/src/pipes/sd-group.pipe.d.ts

@@ -1,6 +1,7 @@
 import { PipeTransform } from '@angular/core';
 import { SdTableOption } from '../models/table-option.model';
 import { SdTableItem } from '../models/table-item.model';
+import { SdGroupHeaderHost } from '../services/table-selection/table-selection.util';
 import * as i0 from "@angular/core";
 export declare class SdGroupPipe implements PipeTransform {
     /**
@@ -14,10 +15,13 @@ export declare class SdGroupPipe implements PipeTransform {
      * expand/collapse qua các lần transform. Pipe đọc state từ Map; nếu key chưa tồn tại,
      * dùng `!option.group.defaultCollapsed`. Pipe ghi state về Map cho lần read sau.
      *
+     * `host` (optional, owned by component) — nhận danh sách header vừa sinh (để component
+     * sync selection state) và cung cấp callback toggle cho template context.
+     *
      * @example
-     * `_items | sdGroup: _tableOption : groupExpandState`
+     * `_items | sdGroup: _tableOption : groupExpandState : groupHost`
      */
-    transform(items: SdTableItem[], gridOption: SdTableOption, expandState?: Map<string, boolean>): SdTableItem[];
+    transform(items: SdTableItem[], gridOption: SdTableOption, expandState?: Map<string, boolean>, host?: SdGroupHeaderHost): SdTableItem[];
     static ɵfac: i0.ɵɵFactoryDeclaration<SdGroupPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<SdGroupPipe, "sdGroup", true>;
 }

package/components/table/src/services/table-filter/table-filter.model.d.ts

@@ -2,7 +2,7 @@ import { TemplateRef } from '@angular/core';
 import type { SdSearch } from '@sdcorejs/angular/forms/models';
 import { NestedKeyOf, Operator, Order, PagingReq } from '@sdcorejs/utils/models';
 import { Observable } from 'rxjs';
-import { SdTableColumn } from '../../models/table-column.model';
+import { SdTableColumn, SdTableColumnAnyRow } from '../../models/table-column.model';
 export interface SdTableQuickFilter {
     code: string;
     columnFilter: Record<string, any>;
@@ -18,7 +18,7 @@ export interface TableFilterValue {
     notReload?: boolean;
     filtered?: boolean;
 }
-export interface SdTableFilterRequest<T = any> {
+export interface SdTableFilterRequest<T = unknown> {
     columnOperator: Record<NestedKeyOf<T>, Operator>;
     rawColumnFilter: Record<NestedKeyOf<T>, any>;
     rawExternalFilter: Record<string, any>;
@@ -29,7 +29,7 @@ export interface SdTableFilterRequest<T = any> {
     isExported?: boolean;
     visibledColumns?: SdTableColumn[];
 }
-export interface SdTableOptionFilter<T = any> {
+export 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 */
@@ -54,13 +54,13 @@ export interface SdTableOptionFilter<T = any> {
     onClearFilter?: () => void;
 }
 export declare const SdConvertToPagingReq: (filterRequest: SdTableFilterRequest, args: {
-    columns?: SdTableColumn[];
+    columns?: SdTableColumnAnyRow[];
     externalFilters?: SdTableExternalFilter[];
     fieldMapping?: Record<string, string>;
     orders?: Order[];
 }) => PagingReq;
-export 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> {
+export 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;
@@ -70,23 +70,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;
@@ -96,11 +96,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;
@@ -110,7 +110,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;
@@ -120,7 +120,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;
@@ -128,7 +128,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;

package/components/table/src/services/table-filter/table-filter.service.d.ts

@@ -1,6 +1,6 @@
 import { Operator } from '@sdcorejs/utils/models';
 import { SdTableFilterDefDirective } from '../../directives/sd-table-filter-def.directive';
-import { SdTableColumn } from '../../models/table-column.model';
+import { SdTableColumnAnyRow } from '../../models/table-column.model';
 import { SdTableExternalFilter, SdTableOptionFilter, TableFilterRegister } from './table-filter.model';
 import * as i0 from "@angular/core";
 export declare class SdTableFilterService {
@@ -10,7 +10,7 @@ export declare class SdTableFilterService {
     constructor(...args: unknown[]);
     register: (filter: SdTableOptionFilter | undefined, args: {
         id: string;
-        columns: SdTableColumn[] | undefined;
+        columns: SdTableColumnAnyRow[] | undefined;
         externalFilters: SdTableExternalFilter[] | undefined;
         filterDefs: SdTableFilterDefDirective[] | undefined;
         columnOperator?: Record<string, Operator>;

package/components/table/src/services/table-format/table-format.service.d.ts

@@ -10,7 +10,7 @@ export declare class TableFormatService {
     /**
      * Chuyển đổi dữ liệu thô thành SdTableItem kèm các thiết lập hiển thị (Display Meta)
      */
-    format<T = any>(rawItems: T[], columns: SdTableColumn[], cacheValues: Record<string, any[]>, cacheObjValues: Record<string, Record<string, string>>): Promise<SdTableItem<T>[]>;
+    format<T = unknown>(rawItems: T[], columns: SdTableColumn<T>[], cacheValues: Record<string, any[]>, cacheObjValues: Record<string, Record<string, string>>, rowKey?: string): Promise<SdTableItem<T>[]>;
     static ɵfac: i0.ɵɵFactoryDeclaration<TableFormatService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<TableFormatService>;
 }

package/components/table/src/services/table-selection/selection-action.util.d.ts

@@ -0,0 +1,24 @@
+import { SdTableItem } from '../../models/table-item.model';
+import { SdTableOptionSelector } from '../../models/table-option-selector.model';
+/**
+ * Thu thập danh sách action key khả dụng cho MỘT row.
+ *
+ * why: ghi thẳng vào 2 mảng do caller cấp (in-place) thay vì `return` mảng mới —
+ * hàm này chạy trong đường render (mỗi CD pass, mỗi row) nên không được cấp phát
+ * mảng mới mỗi lần gọi. Caller reset độ dài mảng trước khi gọi.
+ *
+ * Key = `Utilities.hash(action)`, khớp với `ActionFilterPipe` để action bar lọc
+ * đúng action chung của mọi item đang chọn.
+ */
+export declare const collectRowActionKeys: <T>(rowData: SdTableItem<T>, selection: SdTableOptionSelector | undefined, actions: string[], groupedActions: string[]) => void;
+/**
+ * Checkbox "chọn tất cả" ở header có hiển thị hay không.
+ *
+ * why: trước đây là pure 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 do
+ * `SdSelectionVisiblePipe` ghi ở cell BODY, mà CDK render header TRƯỚC body, nên ở pass
+ * đầu mảng luôn rỗng. Hệ quả: checkbox hiện trễ 500ms và mỗi lần re-eval lại đẻ thêm
+ * một timer không ai dọn. Ở đây tự tính key action từ `selection` nên không phụ thuộc
+ * pipe nào chạy trước → quyết định được ngay trong pass hiện tại, không cần timer.
+ */
+export declare const resolveSelectAllVisible: <T>(items: SdTableItem<T>[], selection: SdTableOptionSelector | undefined) => boolean;

package/components/table/src/services/table-selection/table-selection.util.d.ts

@@ -1,8 +1,39 @@
 import { SdTableItem } from '../../models/table-item.model';
 import { SdTableOptionTree } from '../../models/table-option-tree.model';
+import type { SdTableGroupDefContext } from '../../directives/sd-table-group-def.directive';
 export declare const getSelectionRows: <T>(roots: SdTableItem<T>[], treeOpt?: SdTableOptionTree<T>) => SdTableItem<T>[];
 export declare const getSelectedRowData: <T>(rows: SdTableItem<T>[]) => T[];
 export declare const applyDefaultSelected: <T>(roots: SdTableItem<T>[], treeOpt: SdTableOptionTree<T> | undefined, defaultSelected?: (row: T) => boolean) => void;
 export declare const resolveSelectAllState: <T>(visibleRows: SdTableItem<T>[]) => boolean;
 export declare const restorePreservedSelection: <T>(visibleRows: SdTableItem<T>[], preservedSelectedMap: Map<string, SdTableItem<T>>) => void;
 export declare const syncPreservedSelection: <T>(visibleRows: SdTableItem<T>[], preservedSelectedMap: Map<string, SdTableItem<T>>) => SdTableItem<T>[];
+/**
+ * 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.
+ */
+export 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;
+}
+/**
+ * Tính lại `isSelected` / `indeterminate` của một group header và ĐỒNG BỘ sang context.
+ *
+ * why: template trước đây bind `[checked]="isGroupAllSelected(item)"` +
+ * `[indeterminate]="isGroupIndeterminate(item)"` — mỗi binding duyệt toàn bộ children,
+ * mỗi CD pass, cho mỗi group row (và `groupContext()` duyệt thêm lần nữa). Giờ tính MỘT
+ * lần ở selection sync path rồi cache lên meta; template chỉ đọc property.
+ * Một vòng duyệt duy nhất thay cho cặp `every` + `some`.
+ */
+export declare const syncGroupSelectionMeta: <T>(header: SdTableItem<T>) => void;
+/**
+ * Dựng context truyền cho template `sdTableGroupDef`.
+ * Chỉ gọi MỘT lần cho mỗi header (lúc pipe sinh header); sau đó reference được giữ
+ * nguyên và giá trị bên trong cập nhật qua `syncGroupSelectionMeta`.
+ */
+export declare const buildGroupHeaderContext: <T>(header: SdTableItem<T>, host?: SdGroupHeaderHost<T>) => SdTableGroupDefContext<T>;

package/components/table/src/services/tree/tree.util.d.ts

@@ -42,8 +42,9 @@ export declare const subtreeMatches: <T>(data: T, predicate: (data: T) => boolea
  * Lọc mảng children: chỉ giữ child có subtree khớp `predicate`.
  *
  * Trả về MẢNG MỚI nhưng GIỮ NGUYÊN object reference của từng child (không clone)
- * — nhờ vậy `meta.id` (hash từ data) ổn định, selection / trạng thái bung không
- * bị mất khi từ khoá search đổi. Đây là bước "prune" của tính năng search-con.
+ * — nhờ vậy `meta.id` (bám theo identity của object data, hoặc theo `option.rowKey`)
+ * ổn định, selection / trạng thái bung không bị mất khi từ khoá search đổi. Đây là
+ * bước "prune" của tính năng search-con.
  */
 export declare const filterMatchingChildren: <T>(children: T[], predicate: (data: T) => boolean, option?: SdTableOptionTree) => T[];
 export declare const getVisibleChildrenData: <T>(data: T, option: SdTableOptionTree<T>, predicate?: (data: T) => boolean) => T[];

package/components/table/src/table.component.d.ts

@@ -9,7 +9,9 @@ import { SdTableGroupDefDirective, SdTableGroupDefContext } from './directives/s
 import { SdTableFilterDefDirective } from './directives/sd-table-filter-def.directive';
 import { SdMaterialFooterDefDirective } from './directives/sd-table-footer-def.directive';
 import { SdTableTitleDefDirective } from './directives/sd-table-title-def.directive';
+import { SdTableCommandHeaderDefDirective } from './directives/sd-table-command-header-def.directive';
 import { SdTableColumn } from './models/table-column.model';
+import { SdTableCommand } from './models/table-command.model';
 import { SdTableOption } from './models/table-option.model';
 import { SdTableFilterRequest, TableFilterRegister, TableFilterValue } from './services/table-filter/table-filter.model';
 import { CdkDrag, CdkDragDrop, CdkDropList } from '@angular/cdk/drag-drop';
@@ -22,8 +24,9 @@ import { SdPopupExport } from './components/popup-export/popup-export.component'
 import { ISdTableConfiguration } from './configurations';
 import { SdTableItem } from './models/table-item.model';
 import { ConfiguredTableResult } from './models/table-option-config.model';
+import { SdGroupHeaderHost } from './services/table-selection/table-selection.util';
 import * as i0 from "@angular/core";
-export declare class MatPaginatorIntlCro extends MatPaginatorIntl {
+export declare class SdTablePaginatorIntl extends MatPaginatorIntl {
     #private;
     firstPageLabel: string;
     lastPageLabel: string;
@@ -31,8 +34,8 @@ export declare class MatPaginatorIntlCro extends MatPaginatorIntl {
     nextPageLabel: string;
     previousPageLabel: string;
     getRangeLabel: (page: number, pageSize: number, length: number) => string;
-    static ɵfac: i0.ɵɵFactoryDeclaration<MatPaginatorIntlCro, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<MatPaginatorIntlCro>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdTablePaginatorIntl, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SdTablePaginatorIntl>;
 }
 export declare class SdTable<T = unknown> implements AfterViewInit, OnDestroy {
     #private;
@@ -51,6 +54,8 @@ export declare class SdTable<T = unknown> implements AfterViewInit, OnDestroy {
     sdSubInformation: import("@angular/core").Signal<SdTableExpandDefDirective<any> | undefined>;
     sdGroupDef: import("@angular/core").Signal<SdTableGroupDefDirective<any> | undefined>;
     sdCellDefs: import("@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: import("@angular/core").Signal<SdTableCommandHeaderDefDirective | undefined>;
     sdFooterDefs: import("@angular/core").Signal<readonly SdMaterialFooterDefDirective<any>[]>;
     sdFilterDefs: import("@angular/core").Signal<readonly SdTableFilterDefDirective[]>;
     sdTitleDefs: import("@angular/core").Signal<readonly SdTableTitleDefDirective<any>[]>;
@@ -65,6 +70,25 @@ export declare class SdTable<T = unknown> implements AfterViewInit, OnDestroy {
     total: import("@angular/core").WritableSignal<number | undefined>;
     loading: import("@angular/core").WritableSignal<boolean>;
     isSelectAll: import("@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: import("@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: import("@angular/core").Signal<SdTableCommand<T>[]>;
     isFiltered: import("@angular/core").WritableSignal<boolean>;
     requireFiltered: import("@angular/core").WritableSignal<boolean>;
     filterRegister: TableFilterRegister;
@@ -98,6 +122,14 @@ export 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;
     /**
@@ -112,7 +144,21 @@ export declare class SdTable<T = unknown> implements AfterViewInit, OnDestroy {
      * Span TOÀN BỘ width data row vì group row chỉ có 1 cell.
      */
     sdGroupColspan: import("@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;
@@ -128,5 +174,5 @@ export 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: i0.ɵɵFactoryDeclaration<SdTable<any>, never>;
-    static ɵcmp: i0.ɵɵ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: i0.ɵɵ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>;
 }

package/components/tree/src/tree-item-def.directive.d.ts

@@ -1,7 +1,7 @@
 import { TemplateRef } from '@angular/core';
 import { SdTreeItemContext } from './tree.model';
 import * as i0 from "@angular/core";
-export declare class SdTreeItemDefDirective<T = any> {
+export declare class SdTreeItemDefDirective<T = unknown> {
     static ngTemplateContextGuard<T>(_dir: SdTreeItemDefDirective<T>, ctx: unknown): ctx is SdTreeItemContext<T>;
     readonly templateRef: TemplateRef<SdTreeItemContext<T>>;
     static ɵfac: i0.ɵɵFactoryDeclaration<SdTreeItemDefDirective<any>, never>;

package/components/tree/src/tree.component.d.ts

@@ -11,7 +11,7 @@ export interface SdTreeNodeAutoIds {
     label?: string;
     command?: string;
 }
-export interface SdTreeViewCommand<T = any> {
+export interface SdTreeViewCommand<T = unknown> {
     key: string;
     command: SdTreeCommand<T>;
     title: string;
@@ -22,7 +22,7 @@ export interface SdTreeViewCommand<T = any> {
     autoId?: string;
     defaultColor: boolean;
 }
-export interface SdTreeViewNode<T = any> extends SdTreeNode<T> {
+export interface SdTreeViewNode<T = unknown> extends SdTreeNode<T> {
     icon?: string;
     selected: boolean;
     selectionDisabled: boolean;
@@ -35,11 +35,11 @@ export interface SdTreeViewNode<T = any> extends SdTreeNode<T> {
     context: SdTreeItemContext<T>;
     tabIndex: 0 | -1;
 }
-export interface SdTreeSelectionActionView<T = any> {
+export interface SdTreeSelectionActionView<T = unknown> {
     action: SdTreeSelectionAction<T>;
     autoId: string | null;
 }
-export declare class SdTree<T = any> {
+export declare class SdTree<T = unknown> {
     #private;
     readonly autoIdInput: import("@angular/core").InputSignal<string | null | undefined>;
     readonly option: import("@angular/core").InputSignal<SdTreeComponentOption<T> | undefined>;
@@ -71,6 +71,12 @@ export declare class SdTree<T = any> {
     readonly activeNodeId: import("@angular/core").WritableSignal<string | null>;
     readonly normalizedFilterText: import("@angular/core").Signal<string>;
     readonly selectionVisible: import("@angular/core").Signal<boolean>;
+    /**
+     * why: `selector.single` giới hạn đúng một node, nên ô chọn phải là radio — checkbox là ký hiệu
+     * của "chọn nhiều" và người dùng chỉ phát hiện ra giới hạn sau khi tick node thứ hai và thấy node
+     * đầu tự bỏ chọn. `<sd-tree-select>` không multiple sẽ tự rơi vào nhánh này.
+     */
+    readonly selectionSingle: import("@angular/core").Signal<boolean>;
     readonly selectedIdSet: import("@angular/core").Signal<Set<string>>;
     readonly rootNodes: import("@angular/core").Signal<SdTreeNode<T>[]>;
     readonly visibleNodes: import("@angular/core").Signal<SdTreeNode<T>[]>;
@@ -80,6 +86,12 @@ export declare class SdTree<T = any> {
     readonly visibleSelectionActions: import("@angular/core").Signal<SdTreeSelectionAction<T>[]>;
     readonly selectionActionViews: import("@angular/core").Signal<SdTreeSelectionActionView<T>[]>;
     readonly clearSelectionAutoId: import("@angular/core").Signal<string | null>;
+    /**
+     * why: chọn node mà selector KHÔNG khai action nào thì thanh quick-action chỉ còn bộ đếm + nút ✕.
+     * Nó nổi đè lên cây để nói lại đúng thứ checkbox đã nói. Đó cũng là lý do `<sd-tree-select>` —
+     * vốn chỉ chọn rồi bấm "Áp dụng" ở footer modal, không có action nào — không còn thấy thanh này.
+     */
+    readonly selectionQuickActionOpened: import("@angular/core").Signal<boolean>;
     /**
      * Template-facing row model. Expensive/variable values are resolved once per
      * signal recomputation so the HTML does not call helper methods for every CD pass.