@sd-angular/core 19.0.0-beta.99 → 19.0.3

package/components/table/src/configurations/table.configuration.d.ts

@@ -1,7 +1,7 @@
 import { InjectionToken } from '@angular/core';
 import { SdTableOptionPaginate } from '../models/table-option-paginate.model';
 import { SdTableOptionFilter } from '../services/table-filter/table-filter.model';
-import { SdOperator } from '@sd-angular/core/utilities';
+import { Operator } from '@sdcorejs/utils/models';
 import { SdTableColumn } from '../models';
 export interface ISdTableConfiguration {
     paginate?: {
@@ -21,8 +21,8 @@ export interface ISdTableConfiguration {
         /** Ẩn toolbar (xóa bộ lọc, thiết lập) của external filter, khi có ít external filter user không cần chức năng này, mặc định là false */
         hideExternalFilterToolbar?: SdTableOptionFilter['hideExternalFilterToolbar'];
         operator?: {
-            list?: Partial<Record<SdTableColumn['type'], SdOperator[]>>;
-            default?: Partial<Record<SdTableColumn['type'], SdOperator>>;
+            list?: Partial<Record<SdTableColumn['type'], Operator[]>>;
+            default?: Partial<Record<SdTableColumn['type'], Operator>>;
         };
     };
     images?: {

package/components/table/src/directives/index.d.ts

@@ -2,4 +2,5 @@ export * from './sd-table-column-filter-def.directive';
 export * from './sticky-shadow.directive';
 export * from './sd-table-title-def.directive';
 export * from './sd-table-cell-def.directive';
+export * from './sd-table-group-def.directive';
 export * from './sd-column-resize.directive';

package/components/table/src/directives/sd-table-cell-def.directive.d.ts

@@ -1,8 +1,16 @@
 import { TemplateRef } from '@angular/core';
+import { SdTableColumn } from '../models/table-column.model';
 import * as i0 from "@angular/core";
-export declare class SdTableCellDefDirective {
+interface Context<T = any> {
+    item: T;
+    column: SdTableColumn<T>;
+    autoId: string;
+}
+export declare class SdTableCellDefDirective<T = any> {
+    static ngTemplateContextGuard<T>(_dir: SdTableCellDefDirective<T>, _ctx: unknown): _ctx is Context<T>;
     sdTableCellDef: import("@angular/core").InputSignal<string>;
-    templateRef: TemplateRef<any>;
-    static ɵfac: i0.ɵɵFactoryDeclaration<SdTableCellDefDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<SdTableCellDefDirective, "[sdTableCellDef]", never, { "sdTableCellDef": { "alias": "sdTableCellDef"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+    templateRef: TemplateRef<Context<T>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdTableCellDefDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SdTableCellDefDirective<any>, "[sdTableCellDef]", never, { "sdTableCellDef": { "alias": "sdTableCellDef"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
+export {};

package/components/table/src/directives/sd-table-column-filter-def.directive.d.ts

@@ -1,8 +1,16 @@
 import { TemplateRef } from '@angular/core';
+import { SdTableColumn } from '../models/table-column.model';
 import * as i0 from "@angular/core";
-export declare class SdTableColumnFilterDefDirective {
+interface Context<T = any> {
+    column: SdTableColumn<T>;
+    field: string;
+    disabled?: boolean;
+}
+export declare class SdTableColumnFilterDefDirective<T = any> {
+    static ngTemplateContextGuard<T>(_dir: SdTableColumnFilterDefDirective<T>, _ctx: unknown): _ctx is Context<T>;
     sdTableColumnFilterDef: import("@angular/core").InputSignal<string>;
-    templateRef: TemplateRef<any>;
-    static ɵfac: i0.ɵɵFactoryDeclaration<SdTableColumnFilterDefDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<SdTableColumnFilterDefDirective, "[sdTableColumnFilterDef]", never, { "sdTableColumnFilterDef": { "alias": "sdTableColumnFilterDef"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+    templateRef: TemplateRef<Context<T>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdTableColumnFilterDefDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SdTableColumnFilterDefDirective<any>, "[sdTableColumnFilterDef]", never, { "sdTableColumnFilterDef": { "alias": "sdTableColumnFilterDef"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
+export {};

package/components/table/src/directives/sd-table-expand-def.directive.d.ts

@@ -1,7 +1,13 @@
 import { TemplateRef } from '@angular/core';
+import { SdTableItem } from '../models/table-item.model';
 import * as i0 from "@angular/core";
-export declare class SdTableExpandDefDirective {
-    templateRef: TemplateRef<any>;
-    static ɵfac: i0.ɵɵFactoryDeclaration<SdTableExpandDefDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<SdTableExpandDefDirective, "[sdTableExpandDef]", never, {}, {}, never, never, true, never>;
+interface Context<T = any> {
+    item: SdTableItem<T>;
 }
+export declare class SdTableExpandDefDirective<T = any> {
+    static ngTemplateContextGuard<T>(_dir: SdTableExpandDefDirective<T>, _ctx: unknown): _ctx is Context<T>;
+    templateRef: TemplateRef<Context<T>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdTableExpandDefDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SdTableExpandDefDirective<any>, "[sdTableExpandDef]", never, {}, {}, never, never, true, never>;
+}
+export {};

package/components/table/src/directives/sd-table-filter-def.directive.d.ts

@@ -1,13 +1,13 @@
 import { TemplateRef } from '@angular/core';
 import * as i0 from "@angular/core";
 interface Context {
-    externalFilter?: Record<string, any>;
+    externalFilter?: Record<string, unknown>;
 }
 export declare class SdTableFilterDefDirective {
-    static ngTemplateContextGuard(dir: Context, ctx: unknown): ctx is Context;
+    static ngTemplateContextGuard(_dir: SdTableFilterDefDirective, _ctx: unknown): _ctx is Context;
     sdTableFilterDef: import("@angular/core").InputSignal<string>;
     defaultShowing: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
-    templateRef: TemplateRef<any> | null;
+    templateRef: TemplateRef<Context> | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<SdTableFilterDefDirective, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<SdTableFilterDefDirective, "[sdTableFilterDef]", never, { "sdTableFilterDef": { "alias": "sdTableFilterDef"; "required": true; "isSignal": true; }; "defaultShowing": { "alias": "defaultShowing"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }

package/components/table/src/directives/sd-table-footer-def.directive.d.ts

@@ -1,8 +1,16 @@
 import { TemplateRef } from '@angular/core';
+import { SdTableColumn } from '../models/table-column.model';
+import { SdTableItem } from '../models/table-item.model';
 import * as i0 from "@angular/core";
-export declare class SdMaterialFooterDefDirective {
+interface Context<T = any> {
+    items: SdTableItem<T>[];
+    column: SdTableColumn<T>;
+}
+export declare class SdMaterialFooterDefDirective<T = any> {
+    static ngTemplateContextGuard<T>(_dir: SdMaterialFooterDefDirective<T>, _ctx: unknown): _ctx is Context<T>;
     sdTableFooterDef: import("@angular/core").InputSignal<string>;
-    templateRef: TemplateRef<any>;
-    static ɵfac: i0.ɵɵFactoryDeclaration<SdMaterialFooterDefDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<SdMaterialFooterDefDirective, "[sdTableFooterDef]", never, { "sdTableFooterDef": { "alias": "sdTableFooterDef"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+    templateRef: TemplateRef<Context<T>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdMaterialFooterDefDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SdMaterialFooterDefDirective<any>, "[sdTableFooterDef]", never, { "sdTableFooterDef": { "alias": "sdTableFooterDef"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
+export {};

package/components/table/src/directives/sd-table-group-def.directive.d.ts

@@ -0,0 +1,44 @@
+import { TemplateRef } from '@angular/core';
+import { SdTableItem } from '../models/table-item.model';
+import * as i0 from "@angular/core";
+export 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>
+ * ```
+ */
+export declare class SdTableGroupDefDirective<T = any> {
+    static ngTemplateContextGuard<T>(_dir: SdTableGroupDefDirective<T>, _ctx: unknown): _ctx is SdTableGroupDefContext<T>;
+    templateRef: TemplateRef<SdTableGroupDefContext<T>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdTableGroupDefDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SdTableGroupDefDirective<any>, "[sdTableGroupDef]", never, {}, {}, never, never, true, never>;
+}

package/components/table/src/directives/sd-table-title-def.directive.d.ts

@@ -1,8 +1,14 @@
 import { TemplateRef } from '@angular/core';
+import { SdTableColumn } from '../models/table-column.model';
 import * as i0 from "@angular/core";
-export declare class SdTableTitleDefDirective {
+interface Context<T = any> {
+    column: SdTableColumn<T>;
+}
+export declare class SdTableTitleDefDirective<T = any> {
+    static ngTemplateContextGuard<T>(_dir: SdTableTitleDefDirective<T>, _ctx: unknown): _ctx is Context<T>;
     sdTableTitleDef: import("@angular/core").InputSignal<string>;
-    templateRef: TemplateRef<any>;
-    static ɵfac: i0.ɵɵFactoryDeclaration<SdTableTitleDefDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<SdTableTitleDefDirective, "[sdTableTitleDef]", never, { "sdTableTitleDef": { "alias": "sdTableTitleDef"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+    templateRef: TemplateRef<Context<T>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdTableTitleDefDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SdTableTitleDefDirective<any>, "[sdTableTitleDef]", never, { "sdTableTitleDef": { "alias": "sdTableTitleDef"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
+export {};

package/components/table/src/models/index.d.ts

@@ -2,3 +2,4 @@ export * from './table-option.model';
 export * from './table-column.model';
 export * from './table-command.model';
 export * from './table-option-tree.model';
+export type { SdTableItem, SdTableMeta, SdTableDisplay } from './table-item.model';

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

@@ -1,7 +1,7 @@
 import { Signal, TemplateRef } from '@angular/core';
 import { SdBadge } from '@sd-angular/core/components/badge';
 import { SdSearch } from '@sd-angular/core/forms';
-import { SdNestedKeyOf, SdOperator } from '@sd-angular/core/utilities';
+import { NestedKeyOf, Operator } from '@sdcorejs/utils/models';
 import { SdUnwrapSignal } from '@sd-angular/core/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?: {
@@ -46,9 +46,9 @@ interface SdTableColumnBase<T = any> {
         disabled?: boolean;
         default?: any;
         operator?: {
-            default?: SdOperator;
+            default?: Operator;
             enable?: boolean;
-            list?: SdOperator[];
+            list?: Operator[];
         };
         filterDef?: TemplateRef<any>;
     };
@@ -58,12 +58,12 @@ interface SdTableColumnBase<T = any> {
     };
 }
 interface SdTableColumnText<T = any> extends SdTableColumnBase<T> {
-    field: SdNestedKeyOf<T>;
+    field: NestedKeyOf<T>;
     type: 'string';
     useBadge?: UseBadgeFunc<T>;
 }
 interface SdTableColumnNumber<T = any> extends SdTableColumnBase<T> {
-    field: SdNestedKeyOf<T>;
+    field: NestedKeyOf<T>;
     type: 'number';
     useBadge?: UseBadgeFunc<T>;
     filter?: SdTableColumnBase['filter'] & {
@@ -71,7 +71,7 @@ interface SdTableColumnNumber<T = any> extends SdTableColumnBase<T> {
     };
 }
 interface SdTableColumnBool<T = any> extends SdTableColumnBase<T> {
-    field: SdNestedKeyOf<T>;
+    field: NestedKeyOf<T>;
     type: 'boolean';
     useBadge?: UseBadgeFunc<T>;
     option?: {
@@ -80,7 +80,7 @@ interface SdTableColumnBool<T = any> extends SdTableColumnBase<T> {
     };
 }
 interface SdTableColumnDate<T = any> extends SdTableColumnBase<T> {
-    field: SdNestedKeyOf<T>;
+    field: NestedKeyOf<T>;
     type: 'date' | 'datetime' | 'time';
     useBadge?: UseBadgeFunc<T>;
     filter?: SdTableColumnBase['filter'] & {
@@ -88,24 +88,24 @@ interface SdTableColumnDate<T = any> extends SdTableColumnBase<T> {
     };
 }
 export interface SdTableColumnValues<T = any, K = Record<string, any>> extends SdTableColumnBase<T> {
-    field: SdNestedKeyOf<T>;
+    field: NestedKeyOf<T>;
     type: 'values';
     useBadge?: UseBadgeValuesFunc<T, K>;
     option: {
         items: K[] | Signal<K[]> | (() => Promise<K[]>);
-        valueField: SdNestedKeyOf<K>;
-        displayField: SdNestedKeyOf<K>;
+        valueField: NestedKeyOf<K>;
+        displayField: NestedKeyOf<K>;
         selection?: 'MULTIPLE';
     };
 }
 export interface SdTableColumnLazyValues<T = any, K = Record<string, any>> extends SdTableColumnBase<T> {
-    field: SdNestedKeyOf<T>;
+    field: NestedKeyOf<T>;
     type: 'lazy-values';
     useBadge?: UseBadgeFunc<T>;
     option: {
         items: SdSearch<K>;
-        valueField: SdNestedKeyOf<K>;
-        displayField: SdNestedKeyOf<K>;
+        valueField: NestedKeyOf<K>;
+        displayField: NestedKeyOf<K>;
         views?: (values: string[]) => Promise<K[]>;
         selection?: 'MULTIPLE';
     };

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

@@ -1,11 +1,12 @@
-import { MaterialIconFontSet, SdColor } from '@sd-angular/core/utilities/models';
+import { MaterialIconFontSet } from '@sd-angular/core/utilities/models';
+import { Color } from '@sdcorejs/utils/models';
 export interface SdTableCommandOption<T = any> {
     align?: 'left' | 'right';
     commands?: SdTableCommand<T>[];
 }
 export type SdTableCommand<T = any> = SdTableCommandNormal<T> | SdTableCommandChildren<T>;
 export interface SdTableCommandNormal<T = any> {
-    color?: SdColor;
+    color?: Color;
     icon?: string | ((rowData: T) => string);
     fontSet?: MaterialIconFontSet;
     title?: string | ((rowData: T) => string);

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

@@ -18,6 +18,12 @@ export interface SdTableMetaTree<T = any> {
     parentId?: string;
     /** Cached formatted child SdTableItem[] — populated on first expand/format */
     childItems?: SdTableItem<T>[];
+    /**
+     * Hierarchical index path từ root tới row hiện tại — sibling-index (1-based) per level.
+     * Vd root thứ nhất = [1], child thứ 2 của root đó = [1, 2], grandchild thứ 1 = [1, 2, 1].
+     * Template STT join('.') → "1", "1.2", "1.2.1". Populate trong `flattenTree`.
+     */
+    indexPath?: number[];
 }
 export interface SdTableDisplay {
     tooltip?: string;
@@ -32,15 +38,24 @@ export interface SdTableDisplay {
     isHtml: boolean;
     click?: () => void;
 }
+export interface SdTableMetaGroup<T = any> {
+    /** Children items thuộc group này (chỉ set trên group header row). */
+    items?: SdTableItem<T>[];
+    /** true = row này là synthetic group header (sinh bởi SdGroupPipe). */
+    isGroupHeader?: boolean;
+    /** Hash key của group (= Utilities.hash(values)). */
+    key?: string;
+    /** Resolved group-field values (vd `{ customerId: 1, customerName: 'A' }`). */
+    values?: Record<string, any>;
+    /** Trạng thái expand. Chỉ ý nghĩa khi `option.group.collapsible = true`. */
+    isExpanded?: boolean;
+}
 export interface SdTableMeta<T> {
     id: string;
     display: Record<string, SdTableDisplay>;
     selector?: SdTableMetaSelector;
     expand?: SdTableMetaExpand;
-    group?: {
-        htmlTemplate?: string;
-        items?: SdTableItem<T>[];
-    };
+    group?: SdTableMetaGroup<T>;
     tree?: SdTableMetaTree<T>;
 }
 export interface SdTableItem<T = any> {

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

@@ -1,4 +1,4 @@
-import { SdNestedKeyOf } from '@sd-angular/core/utilities';
+import { NestedKeyOf } from '@sdcorejs/utils/models';
 import { SdTableFilterRequest } from '../services/table-filter/table-filter.model';
 export type SdTableOptionExport<T = any> = SdTableOptionExportDefault<T> | SdTableOptionExportCustom;
 export interface SdTableOptionExportDefault<T = any> {
@@ -23,7 +23,7 @@ export interface SdTableOptionExportCustom {
     onExport: (filterRequest: SdTableFilterRequest) => Promise<void>;
 }
 export interface SdTableOptionExportColumn<T = any> {
-    field: SdNestedKeyOf<T>;
+    field: NestedKeyOf<T>;
     title: string;
     description?: string;
     width?: string;
@@ -36,7 +36,7 @@ export interface SdTableOptionExportSheet<T = any> {
     name: string;
     items: T[] | (() => T[] | Promise<T[]>);
     headers: {
-        value: SdNestedKeyOf<T>;
+        value: NestedKeyOf<T>;
         display: string;
     }[];
 }

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

@@ -1,4 +1,21 @@
+import { NestedKeyOf } from '@sdcorejs/utils/models';
 export interface SdTableOptionGroup<T = any> {
-    fields: string[];
-    htmlTemplate: (rowDatas: T[]) => string;
+    /**
+     * Danh sách field dùng để nhóm. Item có cùng giá trị tất cả `fields` sẽ vào cùng group.
+     * Ví dụ `['customerId']` group orders theo khách hàng.
+     * Type-safe qua `NestedKeyOf<T>` — hỗ trợ dot-notation cho nested object (vd `'customer.id'`).
+     */
+    fields: NestedKeyOf<T>[];
+    /**
+     * Mặc định group có collapse được không. true = render với UI có thể expand/collapse;
+     * false = luôn show toàn bộ children (mặc định).
+     */
+    collapsible?: boolean;
+    /** Nếu collapsible, mặc định trạng thái ban đầu: true = collapsed, false = expanded (default). */
+    defaultCollapsed?: boolean;
+    /**
+     * Predicate tùy chọn cho selection. Khi check `selectable` của group header.
+     * Mặc định: chỉ nhóm có >=1 child `selectable` mới hiển thị checkbox.
+     */
+    selectable?: (children: T[]) => boolean;
 }

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

@@ -21,6 +21,22 @@ export interface SdTableOptionSelector<T = any> {
      * Dùng khi cần programmatically set selected items từ bên ngoài.
      */
     defaultSelected?: (rowData: T) => boolean;
+    /**
+     * Giữ lại selection khi user chuyển trang / filter / sort / reload.
+     * Selection chỉ bị clear khi user bấm nút X (onClearSelection) hoặc bỏ chọn từng item.
+     *
+     * - 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).
+     *   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.
+     */
+    preserveSelection?: boolean;
 }
 export type SdTableAction<T = any> = SdTableActionNormal<T> | SdTableActionChildren<T>;
 export interface SdTableActionNormal<T = any> {
@@ -34,7 +50,7 @@ export interface SdTableActionNormal<T = any> {
      * Font set của Material icon.
      * Kiểu thực tế lấy từ `SdButton['fontSet']` và chỉ hỗ trợ các giá trị thuộc `MaterialIconFontSet`,
      * ví dụ: `material-icons`, `material-icons-outlined`, `material-icons-round`,
-     * `material-icons-sharp`, `material-symbols-outlined`.
+     * `material-icons-sharp`.
      * Nếu không truyền, `SdButton` sẽ dùng font set mặc định của nó.
      */
     fontSet?: SdUnwrapSignal<SdButton['fontSet']>;

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

@@ -1,12 +1,100 @@
-export interface SdTableOptionTree<T = any> {
-    /** Key trên object row chứa mảng children. Mặc định: 'children' */
-    childrenKey?: string;
-    /** Giới hạn độ sâu cây. undefined = không giới hạn. */
+import { NestedKeyOf } from '@sdcorejs/utils/models';
+/**
+ * Cấu hình tree-rows cho `<sd-table>` — render dòng con inline dưới dòng cha
+ * kèm expand/collapse.
+ *
+ * Đây là discriminated union theo `loadType`:
+ * - `'static'` ({@link TableOptionTreeStatic}) — children đã nằm sẵn trong data
+ *   (embedded array tại `childrenKey`). Không gọi API khi bung.
+ * - `'lazy'`  ({@link TableOptionTreeLazy})  — children nạp theo yêu cầu qua
+ *   `onExpandChildren` khi người dùng bung dòng lần đầu.
+ *
+ * `loadType` là discriminant: TypeScript dựa vào nó để narrow union (vd chỉ
+ * `static` mới có `childrenKey`/`defaultExpanded`, chỉ `lazy` mới có
+ * `onExpandChildren`). Dùng type-guard `isLazyTree()` trong `tree.util.ts` để
+ * narrow an toàn thay vì truy cập field trực tiếp trên union.
+ *
+ * @example Static (children embedded)
+ * ```ts
+ * tree: { loadType: 'static', childrenKey: 'children', defaultExpanded: 1 }
+ * ```
+ * @example Lazy (nạp theo yêu cầu)
+ * ```ts
+ * tree: { loadType: 'lazy', onExpandChildren: row => api.getChildren(row.id) }
+ * ```
+ */
+export type SdTableOptionTree<T = any> = TableOptionTreeStatic<T> | TableOptionTreeLazy<T>;
+/**
+ * Tree với dữ liệu children **embedded** sẵn trong mỗi row.
+ *
+ * Table đọc mảng con tại `childrenKey` ngay trên object data; không có lời gọi
+ * bất đồng bộ nào khi bung dòng. Đây cũng là chế độ hỗ trợ **search ở cấp con**
+ * cho table `type: 'local'` (xem `tree.util.ts#subtreeMatches` /
+ * `filterMatchingChildren`): khi lọc, một nhánh được giữ lại nếu chính nó hoặc
+ * bất kỳ hậu duệ nào khớp từ khoá, và nhánh khớp sẽ tự bung.
+ */
+export interface TableOptionTreeStatic<T = any> {
+    /** Chế độ nạp children: dữ liệu đã embedded sẵn trong row. */
+    loadType: 'static';
+    /**
+     * Key trên object row chứa mảng children.
+     * Mặc định: `'children'`.
+     */
+    childrenKey?: NestedKeyOf<T> | 'children';
+    /**
+     * Giới hạn độ sâu cây (level gốc = 0).
+     * `undefined` = không giới hạn.
+     */
     maxDepth?: number;
-    /** false | true | number (mở tới cấp N) */
+    /**
+     * Trạng thái bung mặc định khi load:
+     * - `false` — thu gọn hết (mặc định)
+     * - `true`  — bung toàn bộ
+     * - `number N` — bung tới cấp `N` (row có `level < N` được bung)
+     */
     defaultExpanded?: boolean | number;
-    /** Lazy load khi row chưa có children embedded */
-    onExpandChildren?: (rowData: T) => Promise<T[]> | T[];
-    /** Pixel indent mỗi cấp. Mặc định: 20 */
+    /**
+     * Số pixel thụt lề (indent) cho mỗi cấp sâu.
+     * Mặc định: `20`.
+     */
+    indentSize?: number;
+}
+/**
+ * Tree với children **nạp lười (lazy)** theo yêu cầu.
+ *
+ * Khi người dùng bung một dòng lần đầu mà dòng đó chưa có children embedded,
+ * table gọi `onExpandChildren(row)` để nạp; kết quả được cache lại trên row
+ * (ghi vào key `'children'`) nên các lần bung sau không gọi lại.
+ *
+ * Lazy tree **không hỗ trợ** `childrenKey` tuỳ biến (luôn dùng `'children'` làm
+ * nơi lưu kết quả) và **không hỗ trợ** `defaultExpanded` (không thể bung mặc
+ * định nhánh chưa nạp).
+ */
+export interface TableOptionTreeLazy<T = any> {
+    /** Chế độ nạp children: nạp lười theo yêu cầu khi bung. */
+    loadType: 'lazy';
+    /**
+     * Giới hạn độ sâu cây (level gốc = 0).
+     * `undefined` = không giới hạn.
+     */
+    maxDepth?: number;
+    /**
+     * Hàm nạp children khi bung dòng chưa có children embedded.
+     * Trả về `Promise<T[]>`; kết quả được ghi vào key `'children'` của row data
+     * và cache cho các lần bung sau.
+     */
+    onExpandChildren: (rowData: T) => Promise<T[]>;
+    /**
+     * Xác định một row có con hay không — để quyết định có hiển thị icon expand.
+     * - Không truyền: MỌI lazy node đều hiện icon expand (không biết trước được).
+     * - Truyền: chỉ hiện icon khi trả `true`; trả `false` ⇒ row là lá (ẩn icon,
+     *   không gọi `onExpandChildren`).
+     * Lưu ý: nếu row đã có children embedded sẵn thì luôn coi là có con (bỏ qua hàm này).
+     */
+    hasChildren?: (rowData: T) => boolean;
+    /**
+     * Số pixel thụt lề (indent) cho mỗi cấp sâu.
+     * Mặc định: `20`.
+     */
     indentSize?: number;
 }

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

@@ -1,4 +1,4 @@
-import { SdPagingReq } from '@sd-angular/core/utilities';
+import { PagingReq } from '@sdcorejs/utils/models';
 import { SdTableFilterRequest, SdTableOptionFilter } from '../services/table-filter/table-filter.model';
 import { SdTableColumn } from './table-column.model';
 import { SdTableCommand, SdTableCommandOption } from './table-command.model';
@@ -86,6 +86,15 @@ interface SdTableBaseOption<T = any> {
         /** Width của cột (mặc định '50px'). */
         width?: string;
     };
+    /**
+     * Bật cột filler ở cuối row để hấp thụ leftover width khi tổng width các cột data < container.
+     * Khi enabled = true, các cột utility (selection / STT / command) không bị browser stretch trên màn rộng.
+     * Mặc định off — table tự stretch cột data theo `width: 100%` như cũ.
+     */
+    filler?: {
+        /** Bật/tắt cột filler. */
+        enabled?: boolean;
+    };
     /**
      * Cấu hình kéo-thả đổi thứ tự dòng.
      * Chỉ bật khi table cho phép reorder dữ liệu phía client.
@@ -155,7 +164,7 @@ interface SdTableServerOption<T = any> extends SdTableBaseOption<T> {
      * `pagingReq` là dữ liệu paging đã được chuẩn hóa để dễ map sang API backend.
      * Hàm cần trả về `{ items, total }` để table render và tính phân trang.
      */
-    items: (filterRequest: SdTableFilterRequest<T>, pagingReq: SdPagingReq<T>) => Promise<{
+    items: (filterRequest: SdTableFilterRequest<T>, pagingReq: PagingReq<T>) => Promise<{
         items: T[];
         total: number;
     }>;

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

@@ -3,7 +3,21 @@ import { SdTableOption } from '../models/table-option.model';
 import { SdTableItem } from '../models/table-item.model';
 import * as i0 from "@angular/core";
 export declare class SdGroupPipe implements PipeTransform {
-    transform(items: SdTableItem[], gridOption: SdTableOption): SdTableItem[];
+    /**
+     * Nhóm items theo `option.group.fields`. Mỗi group sinh ra 1 synthetic SdTableItem
+     * (group header) đặt trước children. Header có `meta.group.isGroupHeader = true` + `key`
+     * + `values` + `items` + `isExpanded` để template + table consume.
+     *
+     * Khi `option.group.collapsible = true` + group đang collapse → children bị lọc khỏi output.
+     *
+     * `expandState` (optional, owned by component) — Map<key, expanded> giữ trạng thái
+     * 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.
+     *
+     * @example
+     * `_items | sdGroup: _tableOption : groupExpandState`
+     */
+    transform(items: SdTableItem[], gridOption: SdTableOption, expandState?: Map<string, boolean>): SdTableItem[];
     static ɵfac: i0.ɵɵFactoryDeclaration<SdGroupPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<SdGroupPipe, "sdGroup", true>;
 }